confinium_exclusivum_infinitas.h

/**
 * @brief Single-producer, single-consumer byte ring, a segment view over it, and loculus keepouts.
 *
 * @note Nothing of the implementation is written here: mmgr_ring is a run of opaque bytes, and the
 *       state laid into it is declared nowhere a consumer can reach.
 * @note The caller declares the ring and supplies the bytes; every index, mask and span is the ring's.
 * @note Exactly one producer advances head and exactly one consumer advances tail, and so ordering is
 *       all that is needed and no entry takes a lock or a read-modify-write on those two.
 * @note Nothing is ever zeroed: a loculus keeps its bytes after a drop, which lets a restream run again.
 */
#ifndef MMGR_CONFINIUM_EXCLUSIVUM_INFINITAS_H
#define MMGR_CONFINIUM_EXCLUSIVUM_INFINITAS_H
 
#include "config/mmgr_config.h"
 
MMGR_INCIPE_DECLS
 
/**
 * @brief A byte region a pinned loculus keeps out: the storage, its extent, and how far a reader has gone.
 *
 * @note Carried here and not taken from spatium, and so this module reaches nothing outside config.
 */
typedef struct
{
    uint8_t *buf; /**< First byte of the region [BORROWS]. */
    size_t cap;   /**< Bytes at buf. */
    size_t pos;   /**< How far a reader has walked it. */
} mmgr_ring_span;
 
/**
 * @brief Size of the ring storage a caller declares, counted in size_t units.
 *
 * @note The implementation asserts its state fits inside this. A change there fails a build
 *       instead of overrunning a caller's object.
 * @note Most of it is the keepout array, and so raising MMGR_RING_LOCULI may require raising this too;
 *       the assertion names it when that happens. A build sets this the same way it sets the
 *       loculus count, before including this header.
 */
#ifndef MMGR_RING_WORDS
 
#define MMGR_RING_WORDS 40u
#endif
 
/**
 * @brief Loculi a mask can address, which is one bit per loculus in a machine word.
 *
 * @warning A pool wider than this needs a wider mask or a scan; the assertion below names which.
 */
#define MMGR_RING_LOCULI_MAX MMGR_WORD_BITS
 
/**
 * @brief Loculi this build reserves, which a build may set before including this header.
 *
 * @note The keepout spans are most of the ring's storage. A build with no use for the loculus
 *       view sets this to 0 and gets that space back. Every loculus entry then reports empty or
 *       refuses.
 */
#ifndef MMGR_RING_LOCULI
 
#define MMGR_RING_LOCULI 8u
#endif
 
MMGR_STATIC_ASSERT(
    MMGR_RING_LOCULI <= MMGR_RING_LOCULI_MAX,
    "the loculus masks are one machine word; widen them or fall back to a scan past MMGR_RING_LOCULI_MAX");
 
/**
 * @brief Reports whether cap is a power of two.
 *
 * @param[in] cap Value to test.
 * @return        Non-zero when cap has at most one bit set.
 * @warning Also reports true for 0; mmgr_infin_init rejects 0 separately.
 */
#define MMGR_RING_POW2(cap) (((cap) & ((cap) - 1u)) == 0u)
 
/**
 * @brief Wraps an index into a ring of cap bytes.
 *
 * @param[in] i   Index to wrap.
 * @param[in] cap Ring size.
 * @return        The index masked into range.
 * @warning Correct only because cap is a power of two, which mmgr_infin_init enforces.
 */
#define MMGR_RING_WRAP(i, cap) ((i) & ((cap) - 1u))
 
/**
 * @brief Storage a caller declares for one ring, whose contents belong to the implementation.
 *
 * @note MMGR_ALIGN aligns opaque to size_t.
 * @warning The bytes carry no documented layout; the infin calls are the only accessors.
 */
typedef struct
{
    MMGR_ALIGN(sizeof(size_t)) uint8_t opaque[MMGR_RING_WORDS * sizeof(size_t)]; /**< Private ring state. */
} mmgr_ring;
 
/**
 * @brief Arguments for every infin call; each reads only what it needs.
 *
 * @note Every call reads ring; init adds buf, cap and nsegs.
 * @note Members left unset are zero, and the calls that ignore them never read them.
 */
typedef struct
{
    mmgr_ring *const ring;    /**< Ring to act on [BORROWS]. */
    uint8_t *const buf;       /**< Ring bytes, for init [BORROWS]. */
    const size_t cap;         /**< Bytes in buf; a non-zero power of two. */
    const size_t nsegs;       /**< Segments to divide the ring into; a power of two, at most cap. */
    uint8_t *const dst;       /**< Destination for read, read_byte and peek [BORROWS]. */
    const uint8_t *const src; /**< Bytes put writes, or the region hold records [BORROWS]. */
    const size_t bytes;       /**< Byte count the call moves or records. */
    const size_t off;         /**< Offset ahead of the tail that peek starts at. */
    const size_t idx;         /**< Loculus or segment the call acts on. */
    const mmgr_word mask;     /**< Mask loculus_next picks the lowest set bit of. */
    size_t *const out;        /**< Set to the segment index a next or front call chose [BORROWS]. */
} InfinCfg;
 
/**
 * @brief Type of the iteratio_infinita dispatch table.
 *
 * @note MMGR_NS_LAYOUT asserts the twenty members sit at consecutive MMGR_FP_SIZE offsets, with nothing else.
 * @note The first eight are the byte ring, the next six the segment view, the last six the loculi.
 */
typedef struct
{
    mmgr_bool (*init)(const InfinCfg *c);          /**< Lays a fresh ring into the caller's storage. */
    size_t (*available)(const InfinCfg *c);        /**< Bytes waiting to be read. */
    size_t (*vacant)(const InfinCfg *c);           /**< Bytes still free to write. */
    mmgr_bool (*read_byte)(const InfinCfg *c);     /**< Takes one byte and advances the tail. */
    size_t (*read)(const InfinCfg *c);             /**< Takes up to bytes and advances the tail once. */
    void (*peek)(const InfinCfg *c);               /**< Copies bytes out without advancing the tail. */
    void (*consume)(const InfinCfg *c);            /**< Advances the tail past bytes. */
    mmgr_bool (*put)(const InfinCfg *c);           /**< Writes a whole span, or refuses it entire. */
    size_t (*seg_inflight)(const InfinCfg *c);     /**< Segments filled and not yet released. */
    mmgr_bool (*seg_next)(const InfinCfg *c);      /**< Index of the segment the producer fills next. */
    void (*seg_publish)(const InfinCfg *c);        /**< Makes the filled segment visible to the consumer. */
    mmgr_bool (*seg_front)(const InfinCfg *c);     /**< Index of the segment the consumer takes next. */
    void (*seg_release)(const InfinCfg *c);        /**< Frees the front segment. */
    uint8_t *(*seg_at)(const InfinCfg *c);         /**< The contiguous span of one segment. */
    mmgr_word (*loculus_ready)(const InfinCfg *c); /**< Loculi that are free and not pinned. */
    mmgr_iword (*loculus_next)(const InfinCfg *c); /**< Lowest set bit of a mask, or -1. */
    mmgr_bool (*loculus_hold)(const InfinCfg *c);  /**< Takes a loculus and records its keepout. */
    const mmgr_ring_span *(*loculus_keepout)(const InfinCfg *c); /**< The region a pinned loculus keeps out. */
    void (*loculus_drop)(const InfinCfg *c);                     /**< Gives a loculus back, leaving its bytes alone. */
    void (*loculus_mark)(const InfinCfg *c);                     /**< Marks a loculus free. */
} InfinitasNs;
MMGR_NS_LAYOUT(InfinitasNs, init, available, vacant, read_byte, read, peek, consume, put, seg_inflight, seg_next,
               seg_publish, seg_front, seg_release, seg_at, loculus_ready, loculus_next, loculus_hold, loculus_keepout,
               loculus_drop, loculus_mark);
 
/**
 * @brief Lays a fresh ring into c->ring, over the bytes at c->buf.
 *
 * @param[in] c Storage, bytes, capacity and segment count [BORROWS].
 * @return      MMGR_TRUE when the ring is ready, MMGR_FALSE when a size was rejected.
 * @note Refuses a cap or nsegs that is 0 or not a power of two, and an nsegs above cap.
 * @note Marks every loculus free and none pinned.
 * @warning c->ring and c->buf are both the caller's, and c->buf is kept by the ring [BORROWS].
 * @warning c->buf must carry the alignment the caller's own accesses need; this call does not align it.
 */
mmgr_bool mmgr_infin_init(const InfinCfg *c);
 
/**
 * @brief Returns the bytes waiting to be read.
 *
 * @param[in] c Ring to inspect [BORROWS].
 * @return      Distance from the tail to the head, wrapped into the ring.
 * @warning Only a snapshot: a concurrent producer may add more before the caller acts on it.
 */
size_t mmgr_infin_available(const InfinCfg *c);
 
/**
 * @brief Returns the bytes still free to write.
 *
 * @param[in] c Ring to inspect [BORROWS].
 * @return      cap minus one, minus the readable bytes.
 * @note One byte is reserved always, as keeps a full ring apart from an empty one.
 * @warning Only a snapshot: a concurrent consumer may free more before the caller acts on it.
 */
size_t mmgr_infin_vacant(const InfinCfg *c);
 
/**
 * @brief Takes one byte into c->dst and advances the tail past it.
 *
 * @param[in] c Ring and the destination byte [BORROWS].
 * @return      MMGR_TRUE when a byte was taken, MMGR_FALSE when the ring was empty.
 * @note Writes through c->dst only when it returns MMGR_TRUE.
 * @note One byte per call, and so the cost lies in the call; a caller drawing a
 *       run of bytes wants mmgr_infin_read, which moves them a word at a time under one tail store.
 */
mmgr_bool mmgr_infin_read_byte(const InfinCfg *c);
 
/**
 * @brief Takes up to c->bytes into c->dst and advances the tail once at the end.
 *
 * @param[in] c Ring, destination and the most to take [BORROWS].
 * @return      Bytes actually taken, which is 0 when the ring was empty.
 * @note Moves the bytes in at most two runs, and so the wrap costs one extra move and not one per byte.
 * @note Reads the tail once and publishes it once and not per byte.
 * @warning c->dst must be writable for c->bytes.
 */
size_t mmgr_infin_read(const InfinCfg *c);
 
/**
 * @brief Copies c->bytes starting c->off ahead of the tail into c->dst, leaving the tail alone.
 *
 * @param[in] c Ring, destination, byte count and starting offset [BORROWS].
 * @note Moves the bytes in at most two runs, the same way mmgr_infin_read does.
 * @warning Copies c->bytes regardless of whether that many have arrived; read mmgr_infin_available first.
 * @warning A c->bytes above the ring's capacity is clamped there, since one lap is all two runs express.
 */
void mmgr_infin_peek(const InfinCfg *c);
 
/**
 * @brief Advances the tail past c->bytes.
 *
 * @param[in] c Ring and the byte count to drop [BORROWS].
 * @warning Advances regardless of whether that many have arrived; read mmgr_infin_available first.
 */
void mmgr_infin_consume(const InfinCfg *c);
 
/**
 * @brief Writes c->bytes of c->src into the ring, or refuses the whole span.
 *
 * @param[in] c Ring, the bytes to write and their count [BORROWS].
 * @return      MMGR_TRUE when the span was written, MMGR_FALSE when it would not fit.
 * @note Checks the whole span against mmgr_infin_vacant first. A partial write never happens.
 * @note Advances a local head across the wrap and publishes it once, and so no half span is ever visible.
 * @warning c->src must be readable for c->bytes.
 */
mmgr_bool mmgr_infin_put(const InfinCfg *c);
 
/**
 * @brief Returns the segments filled and not yet released.
 *
 * @param[in] c Ring to inspect [BORROWS].
 * @return      The distance between the claim and release counters.
 */
size_t mmgr_infin_seg_inflight(const InfinCfg *c);
 
/**
 * @brief Reports the index of the segment the producer fills next.
 *
 * @param[in] c Ring, and where to write the index [BORROWS].
 * @return      MMGR_FALSE when every segment is in flight.
 * @note Publishing is separate. A half-filled segment is never visible to the consumer.
 */
mmgr_bool mmgr_infin_seg_next(const InfinCfg *c);
 
/**
 * @brief Makes the filled segment visible to the consumer.
 *
 * @param[in] c Ring to advance [BORROWS].
 */
void mmgr_infin_seg_publish(const InfinCfg *c);
 
/**
 * @brief Reports the index of the segment the consumer takes next.
 *
 * @param[in] c Ring, and where to write the index [BORROWS].
 * @return      MMGR_FALSE when none is in flight.
 */
mmgr_bool mmgr_infin_seg_front(const InfinCfg *c);
 
/**
 * @brief Frees the front segment.
 *
 * @param[in] c Ring to advance [BORROWS].
 * @note Segments release in the order they were claimed.
 */
void mmgr_infin_seg_release(const InfinCfg *c);
 
/**
 * @brief Returns the contiguous span of segment c->idx.
 *
 * @param[in] c Ring and the segment index [BORROWS].
 * @return      Its first byte inside the ring buffer [BORROWS].
 */
uint8_t *mmgr_infin_seg_at(const InfinCfg *c);
 
/**
 * @brief Returns the loculi that are free and not pinned.
 *
 * @param[in] c Ring to inspect [BORROWS].
 * @return      The free mask with the pinned ones cleared, bounded to MMGR_RING_LOCULI.
 * @note A loculus is takeable only when both hold, and that leaves reuse safe.
 */
mmgr_word mmgr_infin_loculus_ready(const InfinCfg *c);
 
/**
 * @brief Returns the index of the lowest set bit of c->mask.
 *
 * @param[in] c The mask to pick from [BORROWS].
 * @return      The index, or -1 when c->mask is empty.
 * @note Counts and not scans, and branches on nothing but the empty mask.
 */
mmgr_iword mmgr_infin_loculus_next(const InfinCfg *c);
 
/**
 * @brief Takes loculus c->idx and records the c->bytes at c->src that it keeps out.
 *
 * @param[in] c Ring, the loculus, and the region to record [BORROWS].
 * @return      MMGR_TRUE when this caller took it, MMGR_FALSE when it was already pinned.
 * @note The recorded region stays valid until mmgr_infin_loculus_drop. A reader walks it in place.
 * @warning An out-of-range c->idx names nothing, and so it reads as pinned and is never handed out.
 */
mmgr_bool mmgr_infin_loculus_hold(const InfinCfg *c);
 
/**
 * @brief Returns the region loculus c->idx is keeping out.
 *
 * @param[in] c Ring and the loculus [BORROWS].
 * @return      The recorded span, or NULL when c->idx is out of range [BORROWS].
 * @note Handed back const. A reader walks it without moving the ring's own record.
 */
const mmgr_ring_span *mmgr_infin_loculus_keepout(const InfinCfg *c);
 
/**
 * @brief Gives loculus c->idx back.
 *
 * @param[in] c Ring and the loculus [BORROWS].
 * @note Leaves the recorded span and the bytes alone. A restream can run again.
 */
void mmgr_infin_loculus_drop(const InfinCfg *c);
 
/**
 * @brief Marks loculus c->idx free.
 *
 * @param[in] c Ring and the loculus [BORROWS].
 */
void mmgr_infin_loculus_mark(const InfinCfg *c);
 
MMGR_NS InfinitasNs iteratio_infinita MMGR_UNUSED = {
    .init = mmgr_infin_init,
    .available = mmgr_infin_available,
    .vacant = mmgr_infin_vacant,
    .read_byte = mmgr_infin_read_byte,
    .read = mmgr_infin_read,
    .peek = mmgr_infin_peek,
    .consume = mmgr_infin_consume,
    .put = mmgr_infin_put,
    .seg_inflight = mmgr_infin_seg_inflight,
    .seg_next = mmgr_infin_seg_next,
    .seg_publish = mmgr_infin_seg_publish,
    .seg_front = mmgr_infin_seg_front,
    .seg_release = mmgr_infin_seg_release,
    .seg_at = mmgr_infin_seg_at,
    .loculus_ready = mmgr_infin_loculus_ready,
    .loculus_next = mmgr_infin_loculus_next,
    .loculus_hold = mmgr_infin_loculus_hold,
    .loculus_keepout = mmgr_infin_loculus_keepout,
    .loculus_drop = mmgr_infin_loculus_drop,
    .loculus_mark = mmgr_infin_loculus_mark,
};
 
MMGR_FINIS_DECLS
 
#endif