rtchan.hpp

/*
 * rtchan - Realtime-safe channels via lock-free ringbuffer queues
 * Copyright (c) 2025 Fawn <rubiefawn@gmail.com>
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
#pragma once
#include <algorithm> // std::min()
#include <atomic>
#include <cstring> // std::memcpy()
#include <optional>
#include <new> // std::hardware_destructive_interference_size to eliminate false sharing between indicies
#include <span>
 
namespace rtchan {
 
using std::size_t, std::span;
static_assert(std::atomic_size_t::is_always_lock_free, "rtchan is not useful without lock-free atomic_size_t!");
 
// TODO: Analyze with stoat
// TODO: Dynamic extent variants that have their buffers allocated at runtime
// TODO: Use optional<span<T>> to make failure more type-safe. Currently this
// isn't done since sizeof(optional<span<T>>) > sizeof(span<T>), since optional
// needs to have a way to tell if the span exists or not. I thought perhaps a
// span containing nullptr would be the representation for nullopt, but this is
// apparently not the case for the same reason you can have optional<nullptr_t>.
// If this ever changes, using optional<span<T>> instead of sentinel values
// in these classes would be a massive improvement.
// TODO: Resiliency? If a thread is terminated while it has an uncommitted
// reservation, the entire queue will eventually lock up.
// TODO: Overloads for send() and recv() family of functions that allow a
// custom wait strategy lambda to take the place of the spinlock
// TODO: Variadic overloads for send() and recv() family of functions:
// - std::initializer_list
// - Template pack expansion

template<typename T>
class chan {
public:
    virtual auto try_send(T&& item) noexcept -> bool = 0;

    virtual auto try_send(span<const T>&& items) noexcept -> span<const T> = 0;

    virtual void send(T&& item) noexcept = 0;

    virtual void send(span<const T>&& items) noexcept = 0;

    virtual auto try_recv(T& dest) noexcept -> bool = 0;

    virtual auto try_recv(span<T>& dest) noexcept -> span<T> = 0;

    virtual void recv(T& dest) noexcept = 0;

    virtual void recv(span<T>& dest) noexcept = 0;
    
    // TODO: Specify in documentation that the return value is also a key to pass into commit_send()
    // The returned span is contiguous; it should never wrap around the end of buf
    virtual auto try_reserve_send(size_t count) noexcept -> span<T> = 0;

    // TODO: Specify in documentation that the return value is also a key to pass into commit_send()
    // The returned span is contiguous; it should never wrap around the end of buf
    virtual auto reserve_send_up_to(size_t count) noexcept -> span<T> = 0;

    // TODO: Specify in documentation that the return value is also a key to pass into commit_send()
    virtual auto reserve_send(size_t count) noexcept -> span<T> = 0;

    // TODO: Specify in documentation that @p reservation is obtained by either try_reserve_send(), reserve_send_up_to() or reserve_send()
    virtual auto try_commit_send(span<const T>& reservation) noexcept -> bool = 0;

    // TODO: Specify in documentation that @p reservation is obtained by either try_reserve_send(), reserve_send_up_to() or reserve_send()
    virtual void commit_send(span<const T>& reservation) noexcept = 0;

    // TODO: Specify in documentation that the return value is also a key to pass into commit_recv()
    virtual auto try_reserve_recv(size_t count) noexcept -> span<T> = 0;

    // TODO: Specify in documentation that the return value is also a key to pass into commit_recv()
    virtual auto reserve_recv_up_to(size_t count) noexcept -> span<T> = 0;

    // TODO: Specify in documentation that the return value is also a key to pass into commit_recv()
    // TODO: How to handle wrapping? send/recv functions can do two memcpys, buf is private.
    virtual auto reserve_recv(size_t count) noexcept -> span<T> = 0;

    // TODO: Specify in documentation that @p reservation is obtained by either try_reserve_recv() or reserve_recv()
    virtual auto try_commit_recv(span<const T>& reservation) noexcept -> bool = 0;

    // TODO: Specify in documentation that @p reservation is obtained by either try_reserve_recv() or reserve_recv()
    virtual void commit_recv(span<const T>& reservation) noexcept = 0;
};
 
} // namespace rtchan