Find file
Fetching contributors…
Cannot retrieve contributors at this time
622 lines (473 sloc) 11.7 KB
Ddoc
$(SPEC_S Interfacing to C++,
$(P
While D is fully capable of
$(LINK2 interfaceToC.html, interfacing to C),
its ability to interface to C++ is much more limited.
There are three ways to do it:
)
$(OL
$(LI Use C++'s ability to create a C interface, and then
use D's ability to
$(LINK2 interfaceToC.html, interface with C)
to access that interface.
)
$(LI Use C++'s ability to create a COM interface, and then
use D's ability to
$(LINK2 COM.html, interface with COM)
to access that interface.
)
$(LI Use the limited ability described here to connect
directly to C++ functions and classes.
)
)
<h2>The General Idea</h2>
$(P Being 100% compatible with C++ means more or less adding
a fully functional C++ compiler front end to D.
Anecdotal evidence suggests that writing such is a minimum
of a 10 man-year project, essentially making a D compiler
with such capability unimplementable.
Other languages looking to hook up to C++ face the same
problem, and the solutions have been:
)
$(OL
$(LI Support the COM interface (but that only works for Windows).)
$(LI Laboriously construct a C wrapper around
the C++ code.)
$(LI Use an automated tool such as SWIG to construct a
C wrapper.)
$(LI Reimplement the C++ code in the other language.)
$(LI Give up.)
)
$(P D takes a pragmatic approach that assumes a couple
modest accommodations can solve a significant chunk of
the problem:
)
$(UL
$(LI matching C++ name mangling conventions)
$(LI matching C++ function calling conventions)
$(LI matching C++ virtual function table layout for single inheritance)
)
<h2>Calling C++ Global Functions From D</h2>
$(P Given a C++ function in a C++ source file:)
$(CPPCODE
#include &lt;iostream&gt;
using namespace std;
int foo(int i, int j, int k)
{
cout &lt;&lt; "i = " &lt;&lt; i &lt;&lt; endl;
cout &lt;&lt; "j = " &lt;&lt; j &lt;&lt; endl;
cout &lt;&lt; "k = " &lt;&lt; k &lt;&lt; endl;
return 7;
}
)
$(P In the corresponding D code, $(CODE foo)
is declared as having C++ linkage and function calling conventions:
)
------
extern (C++) int foo(int i, int j, int k);
------
$(P and then it can be called within the D code:)
------
extern (C++) int foo(int i, int j, int k);
void main()
{
foo(1,2,3);
}
------
$(P Compiling the two files, the first with a C++ compiler,
the second with a D compiler, linking them together,
and then running it yields:)
$(CONSOLE
i = 1
j = 2
k = 3
)
$(P There are several things going on here:)
$(UL
$(LI D understands how C++ function names are "mangled" and the
correct C++ function call/return sequence.)
$(LI Because modules are not part of C++, each function with
C++ linkage must be globally unique within the program.)
$(LI There are no __cdecl, __far, __stdcall, __declspec, or other
such nonstandard C++ extensions in D.)
$(LI There are no volatile type modifiers in D.)
$(LI Strings are not 0 terminated in D. See "Data Type Compatibility"
for more information about this. However, string literals in D are
0 terminated.)
)
$(P C++ functions that reside in namespaces cannot be
direcly called from D.
)
<h2>Calling Global D Functions From C++</h2>
$(P To make a D function accessible from C++, give it
C++ linkage:)
---
import std.stdio;
extern (C++) int foo(int i, int j, int k)
{
writefln("i = %s", i);
writefln("j = %s", j);
writefln("k = %s", k);
return 1;
}
extern (C++) void bar();
void main()
{
bar();
}
---
$(P The C++ end looks like:)
$(CPPCODE
int foo(int i, int j, int k);
void bar()
{
foo(6, 7, 8);
}
)
$(P Compiling, linking, and running produces the output:)
$(CONSOLE
i = 6
j = 7
k = 8
)
<h2>Classes</h2>
$(P D classes are singly rooted by Object, and have an
incompatible layout from C++ classes.
D interfaces, however, are very similar to C++ single
inheritance class heirarchies.
So, a D interface with the attribute of $(CODE extern (C++))
will have a virtual function pointer table (vtbl[]) that
exactly matches C++'s.
A regular D interface has a vtbl[] that differs in that
the first entry in the vtbl[] is a pointer to D's RTTI info,
whereas in C++ the first entry points to the first virtual
function.
)
<h2>Calling C++ Virtual Functions From D</h2>
$(P Given C++ source code defining a class like:)
$(CPPCODE
#include &lt;iostream&gt;
using namespace std;
class D
{
public:
virtual int bar(int i, int j, int k)
{
cout &lt;&lt; "i = " &lt;&lt; i &lt;&lt; endl;
cout &lt;&lt; "j = " &lt;&lt; j &lt;&lt; endl;
cout &lt;&lt; "k = " &lt;&lt; k &lt;&lt; endl;
return 8;
}
};
D *getD()
{
D *d = new D();
return d;
}
)
$(P We can get at it from D code like:)
---
extern (C++)
{
interface D
{
int bar(int i, int j, int k);
}
D getD();
}
void main()
{
D d = getD();
d.bar(9,10,11);
}
---
<h2>Calling D Virtual Functions From C++</h2>
$(P Given D code like:)
---
extern (C++) int callE(E);
extern (C++) interface E
{
int bar(int i, int j, int k);
}
class F : E
{
extern (C++) int bar(int i, int j, int k)
{
writefln("i = ", i);
writefln("j = ", j);
writefln("k = ", k);
return 8;
}
}
void main()
{
F f = new F();
callE(f);
}
---
$(P The C++ code to access it looks like:)
$(CPPCODE
class E
{
public:
virtual int bar(int i, int j, int k);
};
int callE(E *e)
{
return e->bar(11,12,13);
}
)
$(P Note:)
$(UL
$(LI non-virtual functions, and static member functions,
cannot be accessed.)
$(LI class fields can only be accessed via virtual getter
and setter methods.)
)
<h2>Function Overloading</h2>
$(P C++ and D follow different rules for function overloading.
D source code, even when calling $(CODE extern (C++)) functions,
will still follow D overloading rules.
)
<h2>Storage Allocation</h2>
$(P C++ code explicitly manages memory with calls to
$(CODE ::operator new()) and $(CODE ::operator delete()).
D allocates memory using the D garbage collector,
so no explicit delete's are necessary.
D's new and delete are not compatible with C++'s
$(CODE ::operator new) and $(CODE::operator delete).
Attempting to allocate memory with C++ $(CODE ::operator new)
and deallocate it with D's $(CODE delete), or vice versa, will
result in miserable failure.
)
$(P D can still explicitly allocate memory using std.c.stdlib.malloc()
and std.c.stdlib.free(), these are useful for connecting to C++
functions that expect malloc'd buffers, etc.
)
$(P If pointers to D garbage collector allocated memory are passed to
C++ functions, it's critical to ensure that that memory will not
be collected by the garbage collector before the C++ function is
done with it. This is accomplished by:
)
$(UL
$(LI Making a copy of the data using std.c.stdlib.malloc() and passing
the copy instead.)
$(LI Leaving a pointer to it on the stack (as a parameter or
automatic variable), as the garbage collector will scan the stack.)
$(LI Leaving a pointer to it in the static data segment, as the
garbage collector will scan the static data segment.)
$(LI Registering the pointer with the garbage collector with the
std.gc.addRoot() or std.gc.addRange() calls.)
)
$(P An interior pointer to the allocated memory block is sufficient
to let the GC
know the object is in use; i.e. it is not necessary to maintain
a pointer to the beginning of the allocated memory.
)
$(P The garbage collector does not scan the stacks of threads not
created by the D Thread interface. Nor does it scan the data
segments of other DLL's, etc.
)
<h2>Data Type Compatibility</h2>
$(TABLE1
<caption>D And C Type Equivalence</caption>
$(TR
$(TH D type)
$(TH C type)
)
$(TR
$(TD $(B void))
$(TD $(B void))
)
$(TR
$(TD $(B byte))
$(TD $(B signed char))
)
$(TR
$(TD $(B ubyte))
$(TD $(B unsigned char))
)
$(TR
$(TD $(B char))
$(TD $(B char) (chars are unsigned in D))
)
$(TR
$(TD $(B wchar))
$(TD $(B wchar_t) (when sizeof(wchar_t) is 2))
)
$(TR
$(TD $(B dchar))
$(TD $(B wchar_t) (when sizeof(wchar_t) is 4))
)
$(TR
$(TD $(B short))
$(TD $(B short))
)
$(TR
$(TD $(B ushort))
$(TD $(B unsigned short))
)
$(TR
$(TD $(B int))
$(TD $(B int))
)
$(TR
$(TD $(B uint))
$(TD $(B unsigned))
)
$(TR
$(TD $(B long))
$(TD $(B long long))
)
$(TR
$(TD $(B ulong))
$(TD $(B unsigned long long))
)
$(TR
$(TD $(B float))
$(TD $(B float))
)
$(TR
$(TD $(B double))
$(TD $(B double))
)
$(TR
$(TD $(B real))
$(TD $(B long double))
)
$(TR
$(TD $(B ifloat))
$(TD no equivalent)
)
$(TR
$(TD $(B idouble))
$(TD no equivalent)
)
$(TR
$(TD $(B ireal))
$(TD no equivalent)
)
$(TR
$(TD $(B cfloat))
$(TD no equivalent)
)
$(TR
$(TD $(B cdouble))
$(TD no equivalent)
)
$(TR
$(TD $(B creal))
$(TD no equivalent)
)
$(TR
$(TD $(B struct))
$(TD $(B struct))
)
$(TR
$(TD $(B union))
$(TD $(B union))
)
$(TR
$(TD $(B enum))
$(TD $(B enum))
)
$(TR
$(TD $(B class))
$(TD no equivalent)
)
$(TR
$(TD $(I type)$(B *))
$(TD $(I type) $(B *))
)
$(TR
$(TD no equivalent)
$(TD $(I type) $(B &amp;))
)
$(TR
$(TD $(I type)$(B [)$(I dim)$(B ]))
$(TD $(I type)$(B [)$(I dim)$(B ]))
)
$(TR
$(TD $(I type)$(B [)$(I dim)$(B ]*))
$(TD $(I type)$(B (*)[)$(I dim)$(B ]))
)
$(TR
$(TD $(I type)$(B []))
$(TD no equivalent)
)
$(TR
$(TD $(I type)$(B [)$(I type)$(B ]))
$(TD no equivalent)
)
$(TR
$(TD $(I type) $(B function)$(B $(LPAREN))$(I parameters)$(B $(RPAREN)))
$(TD $(I type)$(B (*))$(B $(LPAREN))$(I parameters)$(B $(RPAREN)))
)
$(TR
$(TD $(I type) $(B delegate)$(B $(LPAREN))$(I parameters)$(B $(RPAREN)))
$(TD no equivalent)
)
)
$(P These equivalents hold for most 32 bit C++ compilers.
The C++ standard
does not pin down the sizes of the types, so some care is needed.
)
<h2>Structs and Unions</h2>
$(P D structs and unions are analogous to C's.
)
$(P C code often adjusts the alignment and packing of struct members
with a command line switch or with various implementation specific
#pragma's. D supports explicit alignment attributes that correspond
to the C compiler's rules. Check what alignment the C code is using,
and explicitly set it for the D struct declaration.
)
$(P D does not support bit fields. If needed, they can be emulated
with shift and mask operations.
$(LINK2 htod.html, htod) will convert bit fields to inline functions that
do the right shift and masks.
)
<h2>Object Construction and Destruction</h2>
$(P Similarly to storage allocation and deallocation, objects
constructed in D code should be destructed in D,
and objects constructed
in C++ should be destructed in C++ code.
)
<h2>Special Member Functions</h2>
$(P D cannot call C++ special member functions, and vice versa.
These include constructors, destructors, conversion operators,
operator overloading, and allocators.
)
<h2>Runtime Type Identification</h2>
$(P D runtime type identification
uses completely different techniques than C++.
The two are incompatible.)
<h2>C++ Class Objects by Value</h2>
$(P D can access POD (Plain Old Data) C++ structs, and it can
access C++ class virtual functions by reference.
It cannot access C++ classes by value.
)
<h2>C++ Templates</h2>
$(P D templates have little in common with C++ templates,
and it is very unlikely that any sort of reasonable method
could be found to express C++ templates in a link-compatible
way with D.
)
$(P This means that the C++ STL, and C++ Boost, likely will
never be accessible from D.
)
<h2>Exception Handling</h2>
$(P D and C++ exception handling are completely different.
Throwing exceptions across the boundaries between D
and C++ code will likely not work.
)
<h2>Future Developments</h2>
$(P How the upcoming C++0x standard will affect this is not
known.)
$(P Over time, more aspects of the C++ ABI may be accessible
directly from D.)
)
Macros:
TITLE=Interfacing to C++
WIKI=InterfaceToCPP
CATEGORY_SPEC=$0