root/trunk/docsrc/cpp_interface.dd

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