Safely use containers in C++ library interface

Question

When designing a C++ library, I read it is bad practice to include standard library containers like std::vector in the public interface (see e.g. Implications of using std::vector in a dll exported function).

What if I want to expose a function that takes or returns a list of objects? I could use a simple array, but then I would have to add a count parameter, which makes the interface more cumbersome and less safe. Also it wouldn't help much if I wanted to use a map, for example. I guess libraries like Qt define their own containers which are safe to export, but I'd rather not add Qt as a dependency, and I don't want to roll my own containers.

What's the best practice to deal with containers in the library interface? Is there maybe a tiny container implementation (preferably just one or two files I can drop in, with a permissive license) that I can use as "glue"? Or is there even a way to make std::vector etc. safe across .DLL/.so boundaries and with different compilers?

Answer 1

You can implement a template function. This has two advantages:

1. It lets your users decide what sorts of containers they want to use with your interface.
2. It frees you from having to worry about ABI compatibility, because there is no code in your library, it will be instantiated when the user invokes the function.

For example, put this in your header file:

template <typename Iterator>
void foo(Iterator begin, Iterator end)
{
  for (Iterator it = begin; it != end; ++it)
    bar(*it); // a function in your library, whose ABI doesn't depend on any container
}

Then your users can invoke foo with any container type, even ones they invented that you don't know about.

One downside is that you'll need to expose the implementation code, at least for foo.

Edit: you also said you might want to return a container. Consider alternatives like a callback function, as in the gold old days in C:

typedef bool(*Callback)(int value, void* userData);
void getElements(Callback cb, void* userData) // implementation in .cpp file, not header
{
  for (int value : internalContainer)
    if (!cb(value, userData))
      break;
}

That's a pretty old school "C" way, but it gives you a stable interface and is pretty usable by basically any caller (even actual C code with minor changes). The two quirks are the void* userData to let the user jam some context in there (say if they want to invoke a member function) and the bool return type to let the callback tell you to stop. You can make the callback a lot fancier with std::function or whatever, but that might defeat some of your other goals.

Answer 2

Actually this is not only true for STL containers but applies to pretty much any C++ type (in particular also all other standard library types).

Since the ABI is not standardized you can run into all kinds of trouble. Usually you have to provide separate binaries for each supported compiler version to make it work. The only way to get a truly portable DLL is to stick with a plain C interface. This usually leads to something like COM, since you have to ensure that all allocations and matching deallocations happen in the same module and that no details of the actual object layout are exposed to the user.

Answer 3

TL;DR There is no issue if you distribute either the source code or compiled binaries for the various supported sets of (ABI + Standard Library implementation).

In general, the latter is seen as cumbersome (with reasons), thus the guideline.

---

I trust hand-waving guidelines about as far as I can throw them... and I encourage you to do the same.

This guidelines originates from an issue with ABI compatibility: the ABI is a complex set of specifications that defines the exact interface of a compiled library. It is includes notably:

• the memory layout of structures
• the name mangling of functions
• the calling conventions of functions
• the handling of exception, runtime type information, ...
• ...

For more details, check for example the Itanium ABI. Contrary to C which has a very simple ABI, C++ has a much more complicated surface area... and therefore many different ABIs were created for it.

On top of ABI compatibility, there is also an issue with Standard Library Implementation. Most compilers come with their own implementation of the Standard Library, and these implementations are incompatible with each others (they do not, for example, represent a std::vector the same way, even though all implement the same interface and guarantees).

As a result, a compiled binary (executable or library) may only be mixed and matched with another compiled binary if both were compiled against the same ABI and with compatible versions of a Standard Library implementation.

Cheers: no issue if you distribute source code and let the client compile.

Answer 4

If you are using C++11, you can use cppcomponents. https://github.com/jbandela/cppcomponents

This will allow you to use among other things std::vector as a parameter or return value across Dll/or .so files created using different compilers or standard libraries. Take a look at my answer to a similar question for an example Passing reference to STL vector over dll boundary

Note for the example, you need to add a CPPCOMPONENTS_REGISTER(ImplementFiles) after the CPPCOMPONENTS_DEFINE_FACTORY() statement