how to wrap a c library with opaque pointers in c++ binding

Question

I'm looking at wrapping some c libraries in c++ and I'm not sure what is the best way to wrap opaque pointers.

When the C-structure is part of the public API

typedef struct _SomeType
{
    int a;
    int b;
} SomeType_t;

Where there are several "member" functions:

void SomeTypeFoo( SomeType_t* obj, ... );
void SomeTypeBar( SomeType_t* obj, ... );

I like the approach of deriving from the base to simply associate these "member" functions as actual class members. i.e.:

class SomeTypeWrapper:
    public SomeType_t
{
    void foo( ... );
    void bar( ... );
};

As far as my understanding goes, I believe that SomeTypeWrapper is "binary compatable" with struct _SomeType such that SomeTypeWrapper* can be casted toSomeType_t* so that the c++ method implementation might be:

SomeTypeWrapper::foo( ... )
{
    SomeTypeFoo( (SomeType_t*)this, ... );
}

See Note[1].

However, in some libraries they like to keep the definition of the structure private (I suppose this is to allow changes to the implementation without changing the headers/API ). So in the headers I have something like this:

typedef struct _SomeType SomeType_t;

And then all of the "member" functions deal with these opaque pointers. In order to "wrap" these methods into an interface, what I've done so far is to provide a class which contains the pointer.

class SomeTypeWrapper
{
    private:
        SomeType_t* m_data;

    public:
        SomeTypeWrapper( SomeType_t* data ): m_data(data){}
        void foo(...);
        void bar(...);
};

This means that for any function in the c library which returns such an opaque pointer, I have to allocate a new object to carry that pointer around. For a lot of libraries that is probably fine but this design complicates implementing the wrapper and for speedy c-libraries that do a lot of small-object allocation, I suspect that this extra object over-head can lead to a significant performance penalty. In addition, the underlying object may be reference counted so in some cases I have to make decisions about whether SomeWrapperType increases the reference count, implements a copy constructor, has a private constructor, etc.

In most cases I'm happy to pay that penalty for the nicer interface, but I'm looking for other options. Is there a cleaner way of dealing with opaque c-pointers in a c++ wrapper library? Related: is there a good way to implement wrapper classes so that the c++ headers don't have to include the c-library headers AND doesn't require wrapper object allocation?

Note[1]: I believe this cast is safe as long as the same compiler is used and SomeTypeWrapper adds no additional members and has no virtual methods. By same compiler, I'm assuming the c-library compiled by gcc will work with the c++ wrapper compiled by the same gcc. Perhaps that is not guaranteed ?

Answer 1

Your final version of SomeTypeWrapper (in the question) is the way to go forward.

This means that for any function in the c library which returns such an opaque pointer, I have to allocate a new object to carry that pointer around. For a lot of libraries that is probably fine but this design complicates implementing the wrapper and for speedy c-libraries that do a lot of small-object allocation, I suspect that this extra object over-head can lead to a significant performance penalty.

There is no overhead. An instance of a class with one data member and no virtual methods is no bigger than its sole member. If you define the methods inline in the header, there'll be no function call overhead either. So, as long as you don't allocate these instances with new, but on the stack:

SomeTypeWrapper some_object(make_some_object());  // one allocation on the heap

then you have a zero-overhead solution.

Answer 2

If you are wrapping your opaque pointer, you can surely not derive from it. A seemingly attractive method to get some functionality for free, it soon gets messy when you use inheritance where aggregation is intended: your wrapper is not one of the library's objects, instead, it... wraps a library object.

If you treat your wrapper object with the same care as you would treat the library object, there is always one wrapper (at most) for each opaque pointer. You can share your wrapper objects with e.g. a unique_ptr (C++11 has them!). This is a good thing, considering that the wrapped object is a valuable resource.

Speaking of shared pointers, they can take a deleter function as constructor argument:

struct Wrapper : boost::non_copyable 
{
private:
   std::unique_ptr<SomeType> wrapped;
public:
   Wrapper()
   :wrapped(SomeType_create(), &SomeType_destroy)
   // upon destruction of wrapped, use SomeType_destroy
   {
   }

   void foo() { SomeType_foo(wrapped.get()); }
   int bar(int i) { return SomeType_bar(wrapped.get(),i); }
};

Yes: you will need a method wrapper for each member function in the SomeType; that's completely normal since C++ uses a different calling convention than C and you're bound to replace each C-style member-function with a C++ one.

And you have to take care that you create exactly one wrapper per library object; this object is under your control, and you can share it with whoever you trust with it, but it will be just one object.