Merge pull request #1 from connectivecpp/develop

Merge develop to main

Author: cliffg-softwarelibre

.github/workflows/build_run_unit_test_cmake.yml

@@ -0,0 +1,31 @@
+# Build, run unit tests
+name: CMake build and run unit test matrix
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+env:
+  BUILD_TYPE: Release
+jobs:
+  build_matrix:
+    strategy:
+      matrix:
+        # os: [ubuntu-latest, windows-latest, macos-14]
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: create-build-dir
+        run: mkdir build
+      - name: configure-cmake
+        run: cd build && cmake -D SHARED_BUFFER_BUILD_TESTS:BOOL=ON -D SHARED_BUFFER_BUILD_EXAMPLES:BOOL=ON ..
+      - name: build
+        run: cd build && cmake --build . --config $BUILD_TYPE
+      - name: run-unit-test
+        run: cd build && ctest -C $BUILD_TYPE

.github/workflows/gen_docs.yml

@@ -0,0 +1,28 @@
+# Build, run unit tests
+name: Generate documentation
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build_matrix:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: run-doxygen
+        uses: mattnotmitt/doxygen-action@v1.9.8
+        with:
+          working-directory: doc
+      - name: deploy-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doc/doc_output/html

CMakeLists.txt

@@ -0,0 +1,51 @@
+# Copyright (c) 2024 by Cliff Green
+#
+# https://github.com/connectivecpp/shared-buffer
+#
+# I'm still learning CMake, so improvement suggestions are always welcome.
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+cmake_minimum_required ( VERSION 3.14 FATAL_ERROR )
+
+project ( shared_buffer 
+	  LANGUAGES CXX 
+	  DESCRIPTION "Reference counted character buffer classes"
+	  HOMEPAGE_URL "https://github.com/connectivecpp/shared-buffer/" )
+
+option ( SHARED_BUFFER_BUILD_TESTS "Build unit tests" OFF )
+option ( SHARED_BUFFER_BUILD_EXAMPLES "Build examples" OFF )
+option ( SHARED_BUFFER_INSTALL "Install header only library" OFF )
+
+# add library targets
+
+add_library ( shared_buffer INTERFACE )
+add_library ( chops::shared_buffer ALIAS shared_buffer )
+
+# configure library target
+
+target_include_directories ( shared_buffer INTERFACE
+                             $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/>
+			     $<INSTALL_INTERFACE:include/> )
+target_compile_features ( shared_buffer INTERFACE cxx_std_20 )
+
+# check to build unit tests
+if ( ${SHARED_BUFFER_BUILD_TESTS} )
+  enable_testing()
+  add_subdirectory ( test )
+endif ()
+
+# check to build example code
+if ( ${SHARED_BUFFER_BUILD_EXAMPLES} )
+  add_subdirectory ( example )
+endif ()
+
+# check to install
+if ( ${SHARED_BUFFER_INSTALL} )
+  set ( CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.txt )
+  include ( CPack )
+endif ()
+
+# end of file
+

README.md

@@ -1,2 +1,66 @@
-# shared-buffer
-A reference counted character buffer class template
+# Shared Buffer, Header-Only C++ 20 Reference Counted Byte Buffer Classes
+
+#### Unit Test and Documentation Generation Workflow Status
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/shared-buffer/build_run_unit_test_cmake.yml?branch=main&label=GH%20Actions%20build,%20unit%20tests%20on%20main)
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/shared-buffer/build_run_unit_test_cmake.yml?branch=develop&label=GH%20Actions%20build,%20unit%20tests%20on%20develop)
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/shared-buffer/gen_docs.yml?branch=main&label=GH%20Actions%20generate%20docs)
+
+![GH Tag](https://img.shields.io/github/v/tag/connectivecpp/shared-buffer?label=GH%20tag)
+
+## 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). There are efficient (move) operations for creating a `const_shared_buffer` from a `mutable_shared_buffer`, which allows the use case of creating a message and serializing its contents, then sending 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](https://connectivecpp.github.io/shared-buffer/).
+
+## Dependencies
+
+The `shared_buffer` header file does not have any third-party dependencies. It uses C++ standard library headers only. The unit test code does 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](https://github.com/catchorg/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](https://github.com/cpm-cmake/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](https://github.com/connectivecpp/utility-rack).
+
+Specific version (or branch) specs for the dependenies are in `test/CMakeLists.txt`.
+
+## 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.
+

cmake/download_cpm.cmake

@@ -0,0 +1,10 @@
+
+# copied from CPM.cmake GitHub site
+# download CPM.cmake
+
+file(
+  DOWNLOAD
+  https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.39.0/CPM.cmake
+  ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake
+)
+include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)