More changes, adding example CMake, doc enhancements

Author: cliffg-softwarelibre

README.md

@@ -12,7 +12,7 @@
 
 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 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).
 
@@ -36,7 +36,9 @@ Continuous integration workflows build and unit test on g++ (through Ubuntu), MS
 
 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.
 
-Specific version (or branch) specs for the Catch2 dependency is in `test/CMakeLists.txt`.
+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
 

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)

example/CMakeLists.txt

@@ -0,0 +1,17 @@
+# Copyright (c) 2024 by Cliff Green
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
+
+cmake_minimum_required ( VERSION 3.14 FATAL_ERROR )
+
+# create project
+project ( shared_buffer_example LANGUAGES CXX )
+
+# add executable
+add_executable ( shared_buffer_example shared_buffer_example.cpp )
+target_compile_features ( shared_buffer_example PRIVATE cxx_std_20 )
+
+# link dependencies
+target_link_libraries ( shared_buffer_example PRIVATE shared_buffer )
+

example/shared_buffer_example.cpp

@@ -0,0 +1,121 @@
+/** @file
+ *  
+ *  @brief Example code demonstrating use of @c chops::shared_buffer and
+ *  @c chops::repeat. See @c threaded_wait_shared_demo.cpp for multithreaded
+ *  example.
+ * 
+ *  @ingroup example_module
+ *
+ *  @author Thurman Gillespy
+ * 
+ *  Copyright (c)2019 by Thurman Gillespy
+ *  3/22/19
+ *
+ *  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)
+ * 
+ *  Sample make file: 
+ *  g++ -std=c++17 -I ~/Projects/utility-rack/include/ \
+ *  -I ~/Projects/boost_1_69_0/ \
+ *  shared_buffer_demo.cpp
+ *  
+ * 
+ */
+
+#include <iostream>
+#include <cstdlib> // EXIT_SUCCESS
+#include <cstddef> // std::byte
+#include <cstdint> // std::uint16_t
+#include <string>
+
+#include "marshall/extract_append.hpp"
+#include "marshall/shared_buffer.hpp"
+#include "utility/repeat.hpp"
+
+// tasty utility lambda function
+constexpr auto printLn = [] () { std::cout << std::endl; };
+
+// utility functions for casting @c wait_queue.data()
+template <class C>
+const char* cast_to_char_ptr (const C& buf) {
+    return static_cast<const char*> (static_cast<const void*> (buf.data()));
+}
+
+template <class C>
+const std::uint16_t* cast_to_uint16_ptr (const C& buf) {
+    return static_cast<const std::uint16_t*> (static_cast<const void*> (buf.data()));
+}
+
+
+int main() {
+    
+    // create empty shared buffer1
+    chops::mutable_shared_buffer buf1;
+
+    std::cout << "buffer1 contains " << buf1.size() << " bytes" << std::endl;
+    // c-string to add to buffer1
+    constexpr char str1[] = "A cat in the hat.";
+    const char* strptr = str1;
+
+    // add one char at a time, inside chops::repeat
+    chops::repeat(sizeof(str1),
+        [&] () { buf1.append(static_cast<std::byte> (*strptr++)); });
+    
+    // what str1 and chops::repeat replaces
+    // buf1.append(static_cast<std::byte>('A');
+    // buf1.append((static_cast<std::byte>(' ');
+    // buf1.append((static_cast<std::byte>('c');
+    // etc. 
+
+    std::cout << "buffer1 contains " << buf1.size() << " bytes" << std::endl;
+    // print the output, one char at a time
+    const char* byte = cast_to_char_ptr (buf1); // data starts here
+    for (unsigned int i = 0; i <  buf1.size(); ++i) {
+        std::cout << *byte++;
+    }
+    printLn();
+
+    // append a string with one call to append
+    buf1.clear(); // empty the buffer
+    std::cout << "buffer1 contains " << buf1.size() << " bytes" << std::endl;
+    const std::string str = "Green eggs and ham.";
+    // convert str to C-string, add to buffer1
+    buf1.append(str.c_str(), str.size() + 1); 
+    std::cout << "buffer1 contains " << buf1.size() << " bytes" << std::endl;
+    // print c-string
+    std::cout << cast_to_char_ptr (buf1) << std::endl;
+
+    
+    // write some short ints to a buffer
+    constexpr int NUM_INTS = 15;
+    chops::mutable_shared_buffer buf2(NUM_INTS * sizeof(std::uint16_t));
+    std::cout << "buffer2 contains " << buf2.size() << " bytes and ";
+    std::cout << (buf2.size()/sizeof(std::uint16_t)) << " short integers\n";
+
+    // input some numbers using chops::repeat
+    const std::uint16_t* data = cast_to_uint16_ptr (buf2);// data starts here
+    std::uint16_t* valptr = const_cast<std::uint16_t*>(data); // remove const*
+
+    // create number, convert to 'network' (big endian) byte order, place into buf2
+    std::uint16_t count = 1;
+    chops::repeat(NUM_INTS, [count, x = buf2.data()] () mutable {auto sz =
+        chops::append_val <std::uint16_t> (x, count++ * 5); x += sz; });
+
+    // print them out
+    valptr = const_cast<std::uint16_t*> (data);
+    // read 2 bytes, convert back to proper endian order, print
+    auto f = [x = buf2.data()] () mutable { std::cout << chops::extract_val<std::uint16_t>(x) << " "; x+=2;};
+    chops::repeat(NUM_INTS, f);
+    printLn();
+
+    // swap the buffers, print result
+    buf2.swap(buf1);
+    std::cout << "buffer2 contents after swap" << std::endl;
+    std::cout << cast_to_char_ptr (buf2) << std::endl;
+    std::cout << "buffer1 contents after swap" << std::endl;
+    valptr = const_cast<std::uint16_t*> (data);
+    chops::repeat(NUM_INTS, f); 
+    printLn();
+
+    return EXIT_SUCCESS;
+}

include/buffer/shared_buffer.hpp

@@ -44,12 +44,12 @@
 #include <cstddef> // std::byte
 #include <vector>
 #include <memory> // std::shared_ptr
+#include <compare> // spaceship operator
+#include <span>
 
 #include <utility> // std::move, std::swap
 #include <cstring> // std::memcpy
 
-#include "utility/cast_ptr_to.hpp"
-
 namespace chops {
 
 class const_shared_buffer;

test/CMakeLists.txt

@@ -16,9 +16,10 @@ target_compile_features ( shared_buffer_test PRIVATE cxx_std_20 )
 include ( ../cmake/download_cpm.cmake )
 
 CPMAddPackage ( "gh:catchorg/Catch2@3.5.4" )
+CPMAddPackage ( "gh:connectivecpp/utility-rack@1.0.0" )
 
 # link dependencies
-target_link_libraries ( shared_buffer_test PRIVATE Catch2::Catch2WithMain )
+target_link_libraries ( shared_buffer_test PRIVATE utility_rack Catch2::Catch2WithMain )
 
 enable_testing()
 

test/shared_buffer_test.cpp

@@ -1,27 +1,26 @@
 /** @file
  *
- *  @ingroup test_module
+ * @brief Test scenarios for @c mutable_shared_buffer and
+ * @c const_shared_buffer classes.
  *
- *  @brief Test scenarios for @c mutable_shared_buffer and
- *  @c const_shared_buffer classes.
+ * @author Cliff Green
  *
- *  @author Cliff Green
+ * Copyright (c) 2017-2024 by Cliff Green
  *
- *  Copyright (c) 2017-2018 by Cliff Green
- *
- *  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)
+ * 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)
  *
  */
 
-#include "catch2/catch.hpp"
+#include "catch2/catch_test_macros.hpp"
 
 
 #include <cstddef> // std::byte
 #include <list>
 #include <string_view>
+#include <span>
 
-#include "marshall/shared_buffer.hpp"
+#include "buffer/shared_buffer.hpp"
 
 #include "utility/repeat.hpp"
 #include "utility/make_byte_array.hpp"