The shared_buffer classes are reference counted std::byte buffer classes useful for asynchronous networking. In particular, the Asio asynchronous networking library requires a buffer to be kept alive and valid until the outstanding IO operation (e.g. a network write) is completed. A straightforward and idiomatic way to achieve this is by using reference counted buffers.
There are two classes - const_shared_buffer for outgoing buffers (which should not be modified), and mutable_shared_buffer for incoming buffers (mutable and expandable as data arrives). In addition there are efficient (move) operations for creating a const_shared_buffer from a mutable_shared_buffer. This allows the following common networking use case: create a mutable_shared_buffer, serialize objects into it, then (efficiently) construct a const_shared_buffer and send it out over the network.
While internally all data is kept in std::byte buffers, convenience methods are provided for converting between traditional buffer types (such as char * or unsigned char* or similar).
The generated Doxygen documentation for shared_buffer is here.
The shared_buffer header file does not have any third-party dependencies. It uses C++ standard library headers only. The unit test and example code do have dependencies as noted below.
shared_buffer uses C++ 20 features, including the "spaceship" operator (<=>), std::span, and concepts / requires.
Continuous integration workflows build and unit test on g++ (through Ubuntu), MSVC (through Windows), and clang (through macOS).
The unit test code uses Catch2. If the SHARED_BUFFER_BUILD_TESTS flag is provided to Cmake (see commands below) the Cmake configure / generate will download the Catch2 library as appropriate using the CPM.cmake dependency manager. If Catch2 (v3 or greater) is already installed using a different package manager (such as Conan or vcpkg), the CPM_USE_LOCAL_PACKAGES variable can be set which results in find_package being attempted. Note that v3 (or later) of Catch2 is required.
The unit test uses utilities from Connective C++'s utility-rack.
Specific version (or branch) specs for the dependencies are in the test/CMakeLists.txt file, look for the CPMAddPackage commands.
The example applications use the Connective C++ utility_rack reference counted buffer classes and binary_serialize functions. Specific version (or branch) specs for the dependencies are in the example/CMakeLists.txt file, look for the CPMAddPackage commands.
To build and run the unit test program:
First clone the shared-buffer repository, then create a build directory in parallel to the shared-buffer directory (this is called "out of source" builds, which is recommended), then cd (change directory) into the build directory. The CMake commands:
cmake -D SHARED_BUFFER_BUILD_TESTS:BOOL=ON ../shared-buffer
cmake --build .
ctest
For additional test output, run the unit test individually, for example:
test/shared_buffer_test -s
The example can be built by adding -D SHARED_BUFFER_BUILD_EXAMPLES:BOOL=ON to the CMake configure / generate step.