Shared Buffer, Header-Only C++ 20 Reference Counted Byte Buffer Classes

Unit Test and Documentation Generation Workflow Status

Overview

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 use 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).

Generated Documentation

The generated Doxygen documentation for shared_buffer is here.

Library Dependencies

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.

C++ Standard

shared_buffer uses C++ 20 features, including the "spaceship" operator (<=>), std::span, and concepts / requires.

Supported Compilers

Continuous integration workflows build and unit test on g++ (through Ubuntu), MSVC (through Windows), and clang (through macOS).

Unit Test Dependencies

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.

Example Dependencies

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.

Build and Run Unit Tests

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.