Thursday 28th May 2015 6.22pm

Thu, May 28, 2015

As part of publicising my C++ Now 2015 talk two weeks ago, here is part 16 of 19 from its accompanying Handbook of Examples of Best Practice for C++ ¹¹⁄₁₄ (Boost) libraries:

16. COUPLING: Consider allowing your library users to dependency inject your dependencies on other libraries

As mentioned earlier, the libraries reviewed overwhelmingly chose to use STL11 over any equivalent Boost libraries, so hardcoded std::thread instead of boost::thread, hardcoded std::shared_ptr over boost::shared_ptr and so on. This makes sense right now as STL11 and Boost are still fairly close in functionality, however in the medium term there will be significant divergence between Boost and the STL as Boost "gets ahead" of the STL in terms of features. Indeed, one may find oneself needing to "swap in" Boost to test one's code with some future STL pattern shortly to become standardised.

Let me put this another way: imagine a near future where Boost.Thread has been rewritten atop of the STL11 enhancing the STL11 threading facilities very substantially with lots of cool features which may not enter the standard until the 2020s. If your library is hardcoded to only use the STL, you may lose out on substantial performance or feature improvements. Your users may clamour to be able to use Boost.Thread with your library. You will then have to add an additional code path for Boost.Thread which replicates the STL11 threading path, probably selectable using a macro and the alternative code paths swapped out with #ifdef. But you still may not be done - what if Boost.Chrono also adds significant new features? Or Boost.Regex? Or any of the Boost libraries now standardised into the STL? Before you know it your config.hpp may look like the one from ASIO which has already gone all the way in letting users choose their particular ASIO configuration, and let me quote a mere small section of it to give an idea of what is involved:

… // Standard library support for chrono. Some standard libraries (such as the // libstdc++ shipped with gcc 4.6) provide monotonic_clock as per early C++0x // drafts, rather than the eventually standardised name of steady_clock. #if !defined(ASIO_HAS_STD_CHRONO) # if !defined(ASIO_DISABLE_STD_CHRONO) # if defined(clang) # if defined(ASIO_HAS_CLANG_LIBCXX) # define ASIO_HAS_STD_CHRONO 1 # elif (__cplusplus >= 201103) # if _has_include(<chrono>) # define ASIO_HAS_STD_CHRONO 1 # endif // has_include(<chrono>) # endif // (cplusplus >= 201103) # endif // defined(clang_) # if defined(GNUC) # if ((GNUC__ == 4) && (GNUC_MINOR >= 6)) || (GNUC > 4) # if defined(GXX_EXPERIMENTAL_CXX0X) # define ASIO_HAS_STD_CHRONO 1 # if ((GNUC == 4) && (GNUC_MINOR == 6)) # define ASIO_HAS_STD_CHRONO_MONOTONIC_CLOCK 1 # endif // ((GNUC == 4) && (GNUC_MINOR == 6)) # endif // defined(GXX_EXPERIMENTAL_CXX0X) # endif // ((GNUC == 4) && (GNUC_MINOR >= 6)) || (GNUC > 4) # endif // defined(GNUC) # if defined(ASIO_MSVC) # if (_MSC_VER >= 1700) # define ASIO_HAS_STD_CHRONO 1 # endif // (_MSC_VER >= 1700) # endif // defined(ASIO_MSVC) # endif // !defined(ASIO_DISABLE_STD_CHRONO) #endif // !defined(ASIO_HAS_STD_CHRONO) // Boost support for chrono. #if !defined(ASIO_HAS_BOOST_CHRONO) # if !defined(ASIO_DISABLE_BOOST_CHRONO) # if (BOOST_VERSION >= 104700) # define ASIO_HAS_BOOST_CHRONO 1 # endif // (BOOST_VERSION >= 104700) # endif // !defined(ASIO_DISABLE_BOOST_CHRONO) #endif // !defined(ASIO_HAS_BOOST_CHRONO) …

ASIO currently has over 1000 lines of macro logic in its config.hpp with at least twelve different possible combinations, so that is 2 ^ 12 = 4096 different configurations of code paths (note some combinations may not be allowed in the source code, I didn't check). Are all of these tested equally? I actually don't know, but it seems a huge task requiring many days of testing if they are. However there is a far worse problem here: what happens if library A configures ASIO one way and library B configures ASIO a different way, and then a user combines both libraries A and B into the same process?

The answer is that such a combination violates ODR, and therefore is undefined behaviour i.e. it will crash. This makes the ability to so finely configure ASIO much less useful than it could be.

Let me therefore propose something better: allow library users to dependency inject from the outside the configuration of whether to use a STL11 dependency or its Boost equivalent. If one makes sure to encapsulate the dependency injection into a unique inline namespace, that prevents violation of ODR and therefore collision of the incompatibly configured library dependencies. If the dependent library takes care to coexist with alternative configurations and versions of itself inside the same process, this:

* Forces you to formalise your dependencies (this has a major beneficial effect on design, trust me that your code enormously improves when you are forced to think correctly about this).
* Offers maximum convenience and utility to your library's users.
* Lets you better test your code against multiple (future) STL implementations.
* Looser coupling.
* Much easier upgrades later on (i.e. less maintenance).

What it won't do:
* Prevent API and version fragmentation.
* Deal with balkanisation (i.e. two configurations of your library are islands, and cannot interoperate).

In short whether the pros outweigh the cons comes down to your library's use cases, you as a maintainer, and so on. Indeed you might make use of this technique internally for your own needs, but not expose the facility to choose to your library users.

So how does one implement STL dependency injection in C++ ¹¹⁄₁₄? One entirely valid approach is the ASIO one of a large config.hpp file full of macro logic which switches between Boost and the STL11 for the following header files which were added in C++ 11:

Boost header
array.hpp
atomic.hpp
chrono.hpp
thread.hpp
bind.hpp
thread.hpp
thread.hpp
random.hpp
ratio.hpp
regex.hpp
system/system_error.hpp
thread.hpp
tuple/tuple.hpp
type_traits.hpp
no equivalent
Boost namespace
boost
boost, boost::atomics
boost::chrono
boost
boost
boost
boost
boost::random
boost
boost
boost::system
boost
boost
boost

STL11 header
array
atomic
chrono
condition_variable
functional
future
mutex
random
ratio
regex
system_error
thread
tuple
type_traits
typeindex
STL11 namespace
std
std
std::chrono
std
std
std
std
std
std
std
std
std
std
std
std

At the time of writing, a very large proportion of STL11 APIs are perfectly substitutable with Boost i.e. they have identical template arguments, parameters and type signatures, so all you need to do is to alias either namespace std or namespace boost::? into your own library namespace as follows:

// In config.hpp
namespace mylib { inline namespace MACRO_UNIQUE_ABI_ID {
#ifdef MYLIB_USING_BOOST_RATIO // The external library user sets this
namespace ratio = ::boost;
#else
namespace ratio = ::std;
#endif
} }

// To use inside namespace mylib::MACRO_UNIQUE_ABI_ID, do:
ratio::ratio<2, 1> …

As much as the above looks straightforward, you will find it quickly multiplies into a lot of work just as with ASIO's config.hpp. You will also probably need to do a lot of code refactoring such that every use of ratio is prefixed with a ratio namespace alias, every use of regex is prefixed with a regex namespace alias and so on. So is there an easier way?

Luckily there is, and it is called APIBind. APIBind takes away a lot of the grunt work in the above, specifically:

* APIBind provides bind files for the above C++ 11 header files which let you bind just the relevant part of namespace boost or namespace std into your namespace mylib. In other words, in your namespace mylib you simply go ahead and use ratio<N, D> with no namespace prefix because ratio<N, D> has been bound directly into your mylib namespace for you. APIBind's bind files essentially work as follows:

// In header <ratio> the API being bound
namespace std { template <intmax_t N, intmax_t D = 1> class ratio; }

// Ask APIBind to bind ratio into namespace mylib
#define BOOST_STL11_RATIO_MAP_NAMESPACE_BEGIN namespace mylib {
#define BOOST_STL11_RATIO_MAP_NAMESPACE_END }
#include BOOST_APIBIND_INCLUDE_STL11(bindlib, std, ratio) // If you replace std with boost, you bind boost::ratio<N, D> instead.

// Effect on namespace mylib
namespace mylib { template<intmax_t _0, intmax_t _1 = 1> using ratio = ::std::ratio<_0, _1>; }
// You can now use mylib::ratio<N, D> without prefixing. This is usually a very easy find and replace in files operation.

* APIBind provides generation of inline namespaces with an ABI and version specific mangling to ensure different dependency injection configurations do not collide:

// BOOST_AFIO_V1_STL11_IMPL, BOOST_AFIO_V1_FILESYSTEM_IMPL and BOOST_AFIO_V1_ASIO_IMPL all are set to either boost or std in your config.hpp

// Note the last bracketed item is marked inline. On compilers without inline namespace support this bracketed item is ignored.
#define BOOST_AFIO_V1 (boost), (afio), (BOOST_BINDLIB_NAMESPACE_VERSION(v1, BOOST_AFIO_V1_STL11_IMPL, BOOST_AFIO_V1_FILESYSTEM_IMPL, BOOST_AFIO_V1_ASIO_IMPL), inline)
#define BOOST_AFIO_V1_NAMESPACE BOOST_BINDLIB_NAMESPACE (BOOST_AFIO_V1)
#define BOOST_AFIO_V1_NAMESPACE_BEGIN BOOST_BINDLIB_NAMESPACE_BEGIN(BOOST_AFIO_V1)
#define BOOST_AFIO_V1_NAMESPACE_END BOOST_BINDLIB_NAMESPACE_END (BOOST_AFIO_V1)

// From now on, instead of manually writing namespace boost { namespace afio { and boost::afio, instead do:

BOOST_AFIO_V1_NAMESPACE_BEGIN
struct foo;
BOOST_AFIO_V1_NAMESPACE_END

// Reference struct foo from the global namespace BOOST_AFIO_V1_NAMESPACE::foo;
// Alias hard version dependency into mylib
namespace mylib { namespace afio = BOOST_AFIO_V1_NAMESPACE; }

* APIBind also provides boilerplate for allowing inline reconfiguration of a library during the same translation unit such that the following "just works":

// test_all_multiabi.cpp in the AFIO unit tests
// A copy of AFIO + unit tests completely standalone apart from Boost.Filesystem
#define BOOST_AFIO_USE_BOOST_THREAD 0
#define BOOST_AFIO_USE_BOOST_FILESYSTEM 1
#define ASIO_STANDALONE 1
#include "test_all.cpp"
#undef BOOST_AFIO_USE_BOOST_THREAD
#undef BOOST_AFIO_USE_BOOST_FILESYSTEM
#undef ASIO_STANDALONE

// A copy of AFIO + unit tests using Boost.Thread, Boost.Filesystem and Boost.ASIO
#define BOOST_AFIO_USE_BOOST_THREAD 1
#define BOOST_AFIO_USE_BOOST_FILESYSTEM 1
// ASIO_STANDALONE undefined
#include "test_all.cpp"
#undef BOOST_AFIO_USE_BOOST_THREAD
#undef BOOST_AFIO_USE_BOOST_FILESYSTEM

In other words, you can reset the configuration macros and reinclude afio.hpp to generate a new configuration of AFIO as many times as you like within the same translation unit. This allows header only library A to require a different configuration of AFIO than header only library B, and it all "just works". As APIBind is currently lacking documentation, I'd suggest you review the C++ Now 2015 slides on the topic until proper documentation turns up. The procedure is not hard, and you can examine https://github.com/BoostGSoC13/boost.afio/blob/master/include/boost/afio/config.hpp for a working example of it in action. Do watch out for the comments marking the stanzas which are automatically generated by scripting tools in APIBind, writing those by hand would be tedious.

Presentation slides: https://goo.gl/VHrXrj