feat: coroutine types

.cursorignore

@@ -0,0 +1,25 @@
+/bin
+/bin64
+
+/__build__
+/toolchain.cmake
+
+# Emacs
+*#
+
+# Vim
+*~
+
+# Visual Studio
+/.vs
+/out
+
+# Visual Studio Code
+/.vscode
+CMakeUserPresets.json
+
+# clangd
+/.cache
+/.clangd
+/compile_commands.json
+# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)

.github/workflows/ci.yml

@@ -864,6 +864,13 @@ jobs:
         with:
           path: buffers-root
 
+      - name: Clone Boost.Capy
+        uses: actions/checkout@v3
+        with:
+          path: capy-root
+          repository: cppalliance/capy
+          ref: develop
+
       - name: Setup C++
         uses: alandefreitas/cpp-actions/[email protected]
         id: setup-cpp
@@ -888,8 +895,12 @@ jobs:
           branch: ${{ (github.ref_name == 'master' && github.ref_name) || 'develop' }}
           boost-dir: boost-source
           modules-exclude-paths: ''
-          scan-modules-dir: buffers-root
-          scan-modules-ignore: buffers
+          scan-modules-dir: |
+            buffers-root
+            capy-root
+          scan-modules-ignore: |
+            buffers
+            capy
 
       - name: Patch Boost
         id: patch
@@ -922,6 +933,7 @@ jobs:
 
           # Patch boost-root with workspace module
           cp -r "$workspace_root"/buffers-root "libs/$module"
+          cp -r "$workspace_root"/capy-root libs/capy
 
       - name: Boost B2 Workflow
         uses: alandefreitas/cpp-actions/[email protected]

.gitignore

@@ -16,6 +16,7 @@
 
 # Visual Studio Code
 /.vscode
+CMakeUserPresets.json
 
 # clangd
 /.cache

CMakeLists.txt

@@ -55,6 +55,7 @@ set(BOOST_SRC_DIR ${DEFAULT_BOOST_SRC_DIR} CACHE STRING "Boost source dir to use
 # The boost super-project requires one explicit dependency per-line.
 set(BOOST_BUFFERS_DEPENDENCIES
     Boost::assert
+    Boost::capy
     Boost::config
     Boost::core
     Boost::system

build/Jamfile

@@ -41,7 +41,12 @@ explicit buffers_sources ;
 lib boost_buffers
    : buffers_sources
    : requirements
+     <library>/boost//system
+     <library>/boost//capy
+     <include>../
    : usage-requirements
+     <library>/boost//system
+     <library>/boost//capy
    ;
 
 boost-install boost_buffers ;

doc/modules/ROOT/nav.adoc

@@ -1,9 +1,11 @@
-* xref:1.intro.adoc[]
-* xref:2.algorithms.adoc[]
-* xref:3.dynamic-buffers.adoc[]
-* xref:4.custom-sequences.adoc[]
+* xref:intro.adoc[]
+* xref:algorithms.adoc[]
+* xref:dynamic-buffers.adoc[]
+* xref:custom-sequences.adoc[]
 * Concepts
-** xref:5.1.ConstBufferSequence.adoc[]
-** xref:5.2.MutableBufferSequence.adoc[]
-** xref:5.3.DynamicBuffer.adoc[]
+** xref:ConstBufferSequence.adoc[]
+** xref:MutableBufferSequence.adoc[]
+** xref:DynamicBuffer.adoc[]
+** xref:ReadSource.adoc[]
+** xref:DataSource.adoc[]
 * xref:reference:boost/buffers.adoc[Reference]

doc/modules/ROOT/pages/5.1.ConstBufferSequence.adoc → doc/modules/ROOT/pages/ConstBufferSequence.adoc

@@ -55,3 +55,4 @@ assert( std::equal(
 * cpp:mutable_buffer_1[]
 * cpp:mutable_buffer_pair[]
 * cpp:slice_of[]
+

doc/modules/ROOT/pages/DataSource.adoc

@@ -0,0 +1,100 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/buffers
+//
+
+= DataSource
+
+A __DataSource__ represents a source of data that is available as a constant
+buffer sequence in memory. Unlike a xref:ReadSource.adoc[_ReadSource_],
+which provides data through a streaming `read` interface, a data source
+exposes its entire contents directly through a `data()` member function.
+
+Data sources are useful for representing objects whose binary representation
+is already available in memory and can be accessed without copying, such as
+strings, byte arrays, or memory-mapped files.
+
+== Related Identifiers
+
+cpp:is_data_source[]
+
+== Requirements
+
+* `D` denotes a data source class.
+* `c` denotes a (possibly const) value of type `D`.
+* `T` denotes a type meeting the requirements for xref:ConstBufferSequence.adoc[_ConstBufferSequence_].
+
+[cols="1a,1a,5a"]
+|===
+// Headers
+|Expression|Type|Semantics, Pre/Post-conditions
+
+|`D(D&&)`
+|
+|Data sources must be nothrow move constructible.
+
+|`c.data()`
+|`T`
+|Returns a constant buffer sequence representing the data. This function must
+be `noexcept`. The returned buffer sequence remains valid for at least as long
+as the data source object exists and is not modified.
+
+|===
+
+== Example
+
+[source,cpp]
+----
+struct my_data_source
+{
+    std::string data_;
+
+    explicit my_data_source(std::string s) noexcept
+        : data_(std::move(s))
+    {
+    }
+
+    // Move constructor required
+    my_data_source(my_data_source&&) noexcept = default;
+
+    const_buffer data() const noexcept
+    {
+        return const_buffer(data_.data(), data_.size());
+    }
+};
+
+static_assert(is_data_source<my_data_source>::value, "");
+----
+
+== Comparison with ReadSource
+
+|===
+|Feature|DataSource|ReadSource
+
+|Data access
+|Direct via `data()` returning buffer sequence
+|Streaming via `read()` into caller-provided buffers
+
+|Memory
+|Data must be in memory
+|Data can be generated or streamed
+
+|Multiple reads
+|Implicit (buffer sequence can be iterated multiple times)
+|Requires `rewind()` if available
+
+|Size
+|Implicit (via `buffers::size(data())`)
+|Optional `size()` member
+
+|===
+
+== See Also
+
+* cpp:any_source[] - a type-erased wrapper that can hold either a _DataSource_ or _ReadSource_
+* xref:ReadSource.adoc[_ReadSource_] - a streaming data source concept
+

doc/modules/ROOT/pages/5.3.DynamicBuffer.adoc → doc/modules/ROOT/pages/DynamicBuffer.adoc

@@ -28,8 +28,8 @@ cpp:is_dynamic_buffer[]
 * `a` denotes a value of type `D`.
 * `c` denotes a (possibly const) value of type `D`.
 * `n` denotes a value of type `std::size_t`.
-* `T` denotes a type meeting the requirements for xref:./5.1.ConstBufferSequence.adoc[_ConstBufferSequence_].
-* `U` denotes a type meeting the requirements for xref:./5.2.MutableBufferSequence.adoc[_MutableBufferSequence_].
+* `T` denotes a type meeting the requirements for xref:ConstBufferSequence.adoc[_ConstBufferSequence_].
+* `U` denotes a type meeting the requirements for xref:MutableBufferSequence.adoc[_MutableBufferSequence_].
 
 [cols="1a,1a,5a"]
 |===
@@ -95,3 +95,4 @@ constant or mutable buffer sequences previously obtained using `data()` or
 * `circular_buffer`
 * `flat_buffer`
 * `string_buffer`
+

doc/modules/ROOT/pages/5.2.MutableBufferSequence.adoc → doc/modules/ROOT/pages/MutableBufferSequence.adoc

@@ -53,3 +53,4 @@ assert( std::equal(
 * cpp:mutable_buffer_1[]
 * cpp:mutable_buffer_pair[]
 * cpp:slice_of[]
+