msd::channel

• A synchronized queue that can be easily and safely shared between multiple threads.
• Tested with GCC, Clang, and MSVC.
• Uses std::mutex for synchronization.
• Uses a customizable storage to store elements.

It's a class that can be constructed in several ways:

• Buffered:
  • The channel accepts a specified number of elements, after which it blocks the writer threads and waits for a reader thread to read an element.
  • It blocks the reader threads when channel is empty until a writer thread writes elements.
  • msd::channel<int> chan{2};
• Unbuffered:
  • Never blocks writes.
  • It blocks the reader threads when channel is empty until a writer thread writes elements.
  • msd::channel<int> chan{};
• Heap- or stack-allocated: pass a custom storage or choose a built-in storage:
  • msd::queue_storage (default): uses std::queue
  • msd::vector_storage: uses std::vector (if cache locality is important)
    • msd::channel<int, msd::vector_storage<int>> chan{2};
  • msd::array_storage (always buffered): uses std::array (if you want stack allocation)
    • msd::channel<int, msd::array_storage<int, 10>> chan{};
    • msd::channel<int, msd::array_storage<int, 10>> chan{10}; // does not compile because capacity is already passed as template argument
    • aka msd::static_channel<int, 10>

A storage is:

• A class with a specific interface for storing elements.
• Must implement FIFO logic.
• See built-in storages.

Exceptions:

• msd::operator<< throws msd::closed_channel if channel is closed.
• msd::channel::write returns bool status instead of throwing.
• Heap-allocated storages could throw.
• Static-allocated storage does not throw.
• Throws if stored elements throw.

• Thread-safe push and fetch.
• Use stream operators to push (<<) and fetch (>>) items.
• Value type must be default constructible.
• Blocking (forever waiting to fetch).
• Range-based for loop supported.
• Close to prevent pushing and stop waiting to fetch.
• Integrates with some of the STL algorithms. Eg:
  • std::move(ch.begin(), ch.end(), ...)
  • std::transform(input_chan.begin(), input_chan.end(), msd::back_inserter(output_chan)).
  • std::copy_if(chan.begin(), chan.end(), ...);

Choose one of the methods:

• Copy the include directory into your project and add it to your include path.
• CMake FetchContent
• CMake install - choose a version, then run:

VERSION=X.Y.Z \ && wget https://github.com/andreiavrammsd/cpp-channel/archive/refs/tags/v$VERSION.zip \ && unzip v$VERSION.zip \ && cd cpp-channel-$VERSION \ && mkdir build && cd build \ && cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \ && sudo cmake --install .

• Bazel

#include <cassert> #include <msd/channel.hpp> int main() { msd::channel<int> chan; // Unbuffered int in = 1; int out = 0; // Send to channel chan << in; // Read from channel chan >> out; assert(out == 1); }

#include <cassert> #include <msd/channel.hpp> int main() { msd::channel<int, msd::vector_storage<int>> chan{2}; // Buffered with vector storage // Send to channel chan << 1; // Throws if the channel is closed (after chan.close()) assert(chan.write(2)); // Returns false if the channel is closed (after chan.close()) chan << 3; // Blocks because the capacity is 2 (and no one reads from channel) }

#include <msd/channel.hpp> int main() { msd::channel<int> chan{2}; // Buffered int in = 1; int out = 0; // Send to channel chan << in; chan << in; // Read from channel chan.read(out); chan >> out; chan >> out; // Blocks because the channel is empty (and no one writes on it) }

#include <iostream> #include <msd/channel.hpp> int main() { msd::channel<int, msd::vector_storage<int>> chan; int in1 = 1; int in2 = 2; chan << in1 << in2; for (const auto out : chan) { // Blocks: waits forever for channel items std::cout << out << '\n'; } }

#include <msd/static_channel.hpp> int main() { msd::static_channel<int, 2> chan{}; // Always buffered // Same as msd::channel<int, msd::array_storage<int, 2>> int in = 1; int out = 0; // Send to channel chan.write(in); chan.write(in); // Read from channel chan.read(out); chan.read(out); chan.read(out); // Blocks because the channel is empty (and no one writes on it) }

See examples and documentation.

• In some cases, the integration with some STL algorithms does not compile with MSVC. See the Transform test.

Developed with CLion and Visual Studio Code.