burkey.co /docs/libflint/bytering
index bytering
~/docs/libflint/bytering.md
libflint

Bytering

libflint·Data Structures

A single-producer, single-consumer byte ring over caller-owned storage. Capacity is a power of two of at least 2, one slot is reserved so N bytes hold N-1, and the indexes are C11 atomics whose lock-freedom follows the target's atomic_size_t.

Usage#

The caller provides the backing array and passes it to br_init. That storage must outlive the ring. ByteRing does not allocate or free it. Only the producer calls br_write and br_bulk_write. Only the consumer calls br_read, br_bulk_read, and br_peek.

uint8_t storage[64];
ByteRing ring;
if (br_init(&ring, storage, sizeof(storage)) == 0) {
    if (br_write(&ring, 0xAA) == 0) {
        uint8_t byte;
        if (br_read(&ring, &byte) == 0) {
            /* byte == 0xAA */
        }
    }
}

A failed br_init leaves the handle unchanged. Bulk source and destination buffers must not overlap the backing storage. br_reset is safe only when both sides are idle, and it does not zero the backing storage.

Structs#

ByteRing#

typedef struct {
    uint8_t *buf;
    size_t capacity;
    size_t mask;
    atomic_size_t head;
    atomic_size_t tail;
} ByteRing;

Do not load or store head or tail directly. mask is capacity - 1. Read occupancy with br_available and br_free_space.

Functions#

br_init#

Stores buf and capacity and sets both indexes to 0. capacity must be a power of two and at least 2. Usable space is capacity - 1. Returns 0 on success. Returns -1 if br or buf is NULL, if capacity is less than 2, or if capacity is not a power of two. Failure writes nothing.

int br_init(ByteRing *br, uint8_t *buf, size_t capacity);

br_write#

Appends one byte. Producer only. Returns 0 on success. Returns -1 if br is NULL or the ring is full. On failure the ring is unchanged.

int br_write(ByteRing *br, uint8_t byte);

br_read#

Removes the oldest byte and stores it in *byte. Consumer only. Returns 0 on success. Returns -1 if br or byte is NULL or the ring is empty. On failure the ring is unchanged, and *byte is unchanged when byte is non-NULL.

int br_read(ByteRing *br, uint8_t *byte);

br_peek#

Copies the oldest byte into *byte without removing it. Consumer only. Returns 0 on success. Returns -1 if br or byte is NULL or the ring is empty. On failure *byte is unchanged when byte is non-NULL.

int br_peek(ByteRing *br, uint8_t *byte);

br_bulk_write#

Copies up to n bytes from src. The copy wraps when it crosses the end of the backing storage. Producer only. Returns the number of bytes written. The count is less than n when free space runs out. It is 0 if br or src is NULL, if n is 0, or if the ring is full. A short write still publishes the bytes that fit.

size_t br_bulk_write(ByteRing *br, size_t n, const uint8_t *src);

br_bulk_read#

Copies up to n bytes into dest and removes them. The copy wraps when it crosses the end of the backing storage. Consumer only. Returns the number of bytes read. The count is less than n when the ring holds fewer bytes. It is 0 if br or dest is NULL, if n is 0, or if the ring is empty.

size_t br_bulk_read(ByteRing *br, size_t n, uint8_t *dest);

br_reset#

Sets both indexes to 0. Does not write the backing buffer. A NULL ring is a no-op. Both the producer and the consumer must be idle. This is not a concurrent operation.

void br_reset(ByteRing *br);

br_available#

Returns the number of bytes available to read, (tail - head) & mask. Both indexes are loaded with acquire ordering. With concurrent activity this is an observation, not a reservation. br must be a non-NULL initialized ring.

static inline size_t br_available(const ByteRing *br);

br_free_space#

Returns capacity - 1 - br_available(br). The reserved slot is why this is not capacity - available. br must be a non-NULL initialized ring.

static inline size_t br_free_space(const ByteRing *br);

Macros#

br_capacity#

Returns the backing length N. Usable storage is N-1.

#define br_capacity(br) ((br)->capacity)