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,33 @@
+# 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
+        with:
+          path: main
+      - name: create-build-dir
+        run: mkdir build
+      - name: configure-cmake
+        run: cd build && cmake -D WAIT_QUEUE_BUILD_TESTS:BOOL=ON -D JM_CIRCULAR_BUFFER_BUILD_TESTS:BOOL=OFF ../main/wait-queue
+      - 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: docs
+      - 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/wait-queue
+#
+# 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 ( wait_queue 
+	  LANGUAGES CXX 
+	  DESCRIPTION "A multi producer / multi consumer thread safe wait queue"
+	  HOMEPAGE_URL "https://githug.com/connectivecpp/wait-queue/" )
+
+option ( WAIT_QUEUE_BUILD_TESTS "Build unit tests" OFF )
+option ( WAIT_QUEUE_BUILD_EXAMPLES "Build examples" OFF )
+option ( WAIT_QUEUE_INSTALL "Install header only library" OFF )
+
+# add library targets
+
+add_library ( wait_queue INTERFACE )
+add_library ( chops::wait_queue ALIAS wait_queue )
+
+# configure library target
+
+target_include_directories ( wait_queue INTERFACE
+                             $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/>
+			     $<INSTALL_INTERFACE:include/> )
+target_compile_features ( wait_queue INTERFACE cxx_std_20 )
+
+# check to build unit tests
+if ( ${WAIT_QUEUE_BUILD_TESTS} )
+  enable_testing()
+  add_subdirectory ( test )
+endif ()
+
+# check to build example code
+if ( ${WAIT_QUEUE_BUILD_EXAMPLES} )
+  add_subdirectory ( example )
+endif ()
+
+# check to install
+if ( ${WAIT_QUEUE_INSTALL} )
+  set ( CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.txt )
+  include ( CPack )
+endif ()
+
+# end of file
+

README.md

@@ -1,2 +1,69 @@
-# wait-queue
-Multiple producer / multiple consumer (MPMC) thread-safe queue for passing data between threads
+# `wait-queue` is a header-only C++ 20 MPMC (multiple producer / multiple consumer) thread-safe queue for passing data between threads.
+
+# Unit Test and Documentation Generation Workflow Status
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/wait-queue/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/wait-queue/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/wait-queue/gen_docs.yml?branch=main&label=GH%20Actions%20generate%20docs)
+
+# Overview
+
+`wait_queue` is a multi-reader, multi-writer FIFO queue for transferring data between threads. It is templatized on the type of data passed through the queue as well as the queue container type. Data is passed with value semantics, either by copying or by moving (as opposed to a queue that transfers data by pointer or reference). The wait queue has both wait and no-wait pop semantics. A fixed size container (e.g. a `ring_span`) can be used, eliminating any and all dynamic memory management (useful in embedded or deterministic environments). Similarly, a circular buffer that only allocates on construction can be used, which eliminates dynamic memory management when pushing or popping values on or off the queue.
+
+A graceful shutdown can be performed using the `request_stop` method (modeled on the C++ 20 `request_stop` from `std::stop_source`). This allows waiting reader threads to be notified for shutdown. Alternatively a `std::stop_token` can be passed in to the `wait_queue` constructor, allowing shutdown from outside of the `wait_queue` object.
+
+`wait_queue` is inspired by code from Anthony Williams' Concurrency in Action book, although heavily modified.
+
+Additional documentation can be found dkfjlkjdlkjklj
+
+# Generated Documentation
+
+The generated Doxygen documentation for `wait_queue` is [here](https://connectivecpp.github.io/presentations/).
+
+# Dependencies
+
+The `wait-queue` 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
+
+`wait-queue`  uses C++ 20 features, including `std::stop_token`, `std::stop_source`, `std::condition_variable_any`, `std::scoped_lock`, 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 `WAIT_QUEUE_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 two third-party libraries (each is a single header-only file):
+
+- Martin Moene's [`ring-span-lite`](https://github.com/martinmoene/ring-span-lite)
+- Justas Masiulis' [`circular_buffer`](https://github.com/JustasMasiulis/circular_buffer)
+
+Specific versions and / or branches for the dependencies are in `test/CMakeLists.txt`.
+
+# Build and Run Unit Tests
+
+To build and run the unit test program:
+
+First clone the `wait-queue` repository, then create a build directory in parallel to the presentations directory (this is called "out of source" builds, which is recommended), then `cd` (change directory) into the build directory. The CMake commands:
+
+```
+cmake -D WAIT_QUEUE_BUILD_TESTS:BOOL=ON -D JM_CIRCULAR_BUFFER_BUILD_TESTS:BOOL=OFF ../wait-queue
+
+cmake --build .
+
+ctest
+```
+
+For additional test output, run the unit test individually, for example:
+
+```
+test/wait_queue_test -s
+```
+
+The example can be built by adding `-D WAIT_QUEUE_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)