We will execute the following steps to create an opaque handle type:

The code is as follows:

private struct OpaqueImpl{} // step 1
alias OpaqueImpl* OpaqueHandle; // step 2, pointer method
// or step 2, struct method
// struct OpaqueHandle{ private OpaqueImpl* item; }
// interface functions
OpaqueHandle createObject();
void freeObject(OpaqueHandleimpl);
void add(OpaqueHandleimpl, int);
void print(OpaqueHandleimpl);
void main() {
    // usage:
    auto handle = createObject();
    scope(exit) freeObject(handle);
    handle.add(10); // call using UFCS
    handle.print();
}

Opaque handles are a technique to maximize binary compatibility. Since the user code doesn't need to know anything about the size or layout of the data, the library is free to change its implementation details at any time. It can add functions, add data, or remove data without breaking the client code. Opaque handles are also useful for interlanguage compatibility, since they only require an agreed method to pass basic data and call functions.

With D, we can use this technique directly and also build upon it, while maintaining similar syntax to other library writing techniques. There are four D features used here: alias, UFCS, an empty struct, and wrapper structs.

alias is a feature to give an entity an alternative name. It comes in two mostly equivalent forms: alias oldnamenewname; or alias newname = oldname;. Aliases can hide implementation details (the handle is a pointer, but this is not immediately visible at the usage point) and provide more specific names for your entities, but do not create a new type. This is why we defined the empty struct instead of simply alias void* OpaqueHandle;—the latter form would allow undesired implicit conversions since it does not define a unique type. This is similar to typedef in C++. D used to have typedef too, but it was deprecated in favor of the struct+alias combination to give better control over details. In Phobos, std.typecons.Typedef encapsulates this pattern in the standard library.

Next, we used an empty struct. On the implementation side, this struct would be populated with data; however, on the user interface side, it is empty to hide its details. In D, the implementation and interface may be separated logically using protection attributes or physically by writing two files, one with just declarations and the other with implementations (similar to header files in C or C++). The interface file may be automatically generated with dmd –H. Of course, the implementation may also be written in another language.

Your first thought when declaring an opaque struct might be to write it without a body: struct OpaqueImpl; instead of struct OpaqueImpl {}. We chose the latter here because then the compiler will believe it to have no members instead of being a forward declaration of a struct with an unknown number of members. The advantage of this is we will avoid compiler errors when we try to pass it to functions using method call syntax (UFCS). The compiler will confidently believe it has no members and let you call other functions through it without error. The downside is that a user could also declare OpaqueImpl when it has an empty body, but we are able to prohibit that by simply making the structure private.

Lastly, if we can use a wrapper struct instead of an alias, we have the advantage of being able to add or disable methods, making the handle automatically reference counted, destroyed, or not null, as we've already done with other types in this chapter. If you are writing a library, use a wrapper struct. There's little runtime cost and it has the most potential for growth and control. If you are accessing an existing library, however, be sure to match the method they used. While wrapper structs are almost identical to the wrapped type on a binary level, there are subtle differences in passing them in return values. If you wrap a type you do not control, you should also wrap the functions that use that type.

We looked briefly at the preceding alias syntax. There are two forms; what are the differences between them? Both work the same way; the only difference is the alias old new syntax (inherited from C) has slightly more compatibility with the function pointer attributes and the alias new = old syntax also functions as shorthand for a template, which lets you easily do pass-through or transformations of an argument list. This can be seen in the following code:

// the following two lines are equivalent
alias TemplateArgList(T…) = T;
template TemplateArgList(T…) { alias TemplateArgList = T; }

This is not possible with the other syntax. On the other hand, the C syntax allows you to define names that include function linkage and other attributes:

// this line will not compile with the equals based syntax
alias extern(C) void function() CallbackType;

When interfacing with C, this syntax can help define function pointers with the right linkage (calling convention) and attributes like nothrow. These differences may disappear with time. Currently, outside of these two cases, the syntax you use comes down to personal preference.