File syn_stream.h¶

FileList > src > syntropic > util > syn_stream.h

Cooperative byte stream — protothread-aware ringbuf wrapper. More...

#include "../pt/syn_pt.h"
#include "../util/syn_ringbuf.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_Stream Cooperative byte stream — ringbuf with readability awareness.

Public Functions¶

Type	Name
void	syn_stream_clear_delimiter (SYN_Stream * s) Disable delimiter mode, reverting to default or threshold mode.
size_t	syn_stream_count (const SYN_Stream * s) Return the number of bytes currently in the stream.
void	syn_stream_flush (SYN_Stream * s) Discard all data in the stream.
size_t	syn_stream_free (const SYN_Stream * s) Return the number of free bytes available for writing.
void	syn_stream_init (SYN_Stream * s, uint8_t * buf, size_t size) Initialize a stream with a caller-owned backing buffer.
bool	syn_stream_put (SYN_Stream * s, uint8_t byte) Put a single byte into the stream.
size_t	syn_stream_read (SYN_Stream * s, uint8_t * buf, size_t max_len) Read up to `max_len` bytes from the stream.
size_t	syn_stream_read_line (SYN_Stream * s, uint8_t * buf, size_t max_len) Read up to and including the next delimiter byte.
bool	syn_stream_readable (const SYN_Stream * s) Check if the stream is readable (mode-aware).
void	syn_stream_set_delimiter (SYN_Stream * s, uint8_t delim) Enable delimiter mode.
void	syn_stream_set_threshold (SYN_Stream * s, size_t n) Set the byte threshold for readability.
size_t	syn_stream_write (SYN_Stream * s, const uint8_t * data, size_t len) Write bytes into the stream.

Macros¶

Type	Name
define	PT_STREAM_WAIT (pt, stream) `[PT\_WAIT\_UNTIL](syn__pt_8h.md#define-pt_wait_until)(pt, [syn\_stream\_readable](syn__stream_8c.md#function-syn_stream_readable)(stream))` Wait until the stream is readable (mode-aware).

Detailed Description¶

Composes SYN_RingBuf with readability awareness for cooperative tasks. Three readability modes: * Default: readable when any bytes are available. * Threshold: readable when N+ bytes are available (frame protocols). * Delimiter: readable when a delimiter byte is in the buffer (line protocols).

Producer side is ISR-safe (single-producer / single-consumer). Consumer side integrates with protothreads via PT_STREAM_WAIT.

** **

static uint8_t backing[128];
static SYN_Stream uart_rx;
syn_stream_init(&uart_rx, backing, sizeof(backing));
syn_stream_set_delimiter(&uart_rx, '\n');

// ISR fills the stream:
syn_stream_put(&uart_rx, byte);

// Protothread consumes complete lines:
SYN_PT_Status my_task(SYN_PT *pt, SYN_Task *task) {
    static uint8_t line[80];
    static size_t  n;
    PT_BEGIN(pt);
    for (;;) {
        PT_STREAM_WAIT(pt, &uart_rx);
        n = syn_stream_read_line(&uart_rx, line, sizeof(line));
        process_line(line, n);
    }
    PT_END(pt);
}

** **

syn_stream_set_threshold(&adc_stream, 64);  // wait for 64 bytes
PT_STREAM_WAIT(pt, &adc_stream);
n = syn_stream_read(&adc_stream, frame, 64);

Public Functions Documentation¶

function syn_stream_clear_delimiter¶

Disable delimiter mode, reverting to default or threshold mode.

void syn_stream_clear_delimiter (
    SYN_Stream * s
)

Parameters:

s Stream instance.

function syn_stream_count¶

Return the number of bytes currently in the stream.

size_t syn_stream_count (
    const SYN_Stream * s
)

Parameters:

s Stream instance.

Returns:

Byte count.

function syn_stream_flush¶

Discard all data in the stream.

void syn_stream_flush (
    SYN_Stream * s
)

Parameters:

s Stream instance.

function syn_stream_free¶

Return the number of free bytes available for writing.

size_t syn_stream_free (
    const SYN_Stream * s
)

Parameters:

s Stream instance.

Returns:

Free byte count.

function syn_stream_init¶

Initialize a stream with a caller-owned backing buffer.

void syn_stream_init (
    SYN_Stream * s,
    uint8_t * buf,
    size_t size
)

Parameters:

s Stream instance.
buf Backing array (caller-owned, must outlive the stream).
size Size of backing array. Usable capacity is size - 1.

function syn_stream_put¶

Put a single byte into the stream.

bool syn_stream_put (
    SYN_Stream * s,
    uint8_t byte
)

ISR-safe convenience wrapper around syn_stream_write().

Parameters:

s Stream instance.
byte Byte to store.

Returns:

true if the byte was stored, false if the buffer is full.

function syn_stream_read¶

Read up to max_len bytes from the stream.

size_t syn_stream_read (
    SYN_Stream * s,
    uint8_t * buf,
    size_t max_len
)

Non-blocking — returns 0 if the buffer is empty. Does not respect threshold or delimiter; reads whatever is available.

Parameters:

s Stream instance.
buf Destination buffer.
max_len Maximum bytes to read.

Returns:

Number of bytes actually read.

function syn_stream_read_line¶

Read up to and including the next delimiter byte.

size_t syn_stream_read_line (
    SYN_Stream * s,
    uint8_t * buf,
    size_t max_len
)

Reads bytes from the stream into buf, stopping after the first delimiter byte (which is included in the output). If no delimiter is found in the buffer, returns 0 and reads nothing.

Pair with PT_STREAM_WAIT in delimiter mode to wait for a complete line:

PT_STREAM_WAIT(pt, &stream);
n = syn_stream_read_line(&stream, buf, sizeof(buf));

Parameters:

s Stream instance.
buf Destination buffer.
max_len Maximum bytes to read (including delimiter).

Returns:

Number of bytes read (0 if no delimiter found or empty).

function syn_stream_readable¶

Check if the stream is readable (mode-aware).

bool syn_stream_readable (
    const SYN_Stream * s
)

Behavior depends on configured mode: * Delimiter mode: true if the delimiter byte is in the buffer. * Threshold mode: true if count >= threshold. * Default: true if any bytes are available.

Delimiter mode takes precedence over threshold mode.

Parameters:

s Stream instance.

Returns:

true if the stream has data meeting the readability criteria.

function syn_stream_set_delimiter¶

Enable delimiter mode.

void syn_stream_set_delimiter (
    SYN_Stream * s,
    uint8_t delim
)

When enabled, syn_stream_readable() returns true only when the delimiter byte is present in the buffer. Pair with syn_stream_read_line() to consume one delimited chunk at a time.

Delimiter mode takes precedence over threshold mode.

Parameters:

s Stream instance.
delim Delimiter byte (e.g. '\n').

function syn_stream_set_threshold¶

Set the byte threshold for readability.

void syn_stream_set_threshold (
    SYN_Stream * s,
    size_t n
)

When set to N > 0, syn_stream_readable() returns true only when at least N bytes are in the buffer. Set to 0 to revert to default (readable when any bytes are available).

Parameters:

s Stream instance.
n Byte threshold (0 = any).

function syn_stream_write¶

Write bytes into the stream.

size_t syn_stream_write (
    SYN_Stream * s,
    const uint8_t * data,
    size_t len
)

ISR-safe (single-producer). Writes up to len bytes. Returns the number actually written (may be less if the buffer fills up).

Parameters:

s Stream instance.
data Source data.
len Number of bytes to write.

Returns:

Number of bytes actually written.

Macro Definition Documentation¶

define PT_STREAM_WAIT¶

Wait until the stream is readable (mode-aware).

#define PT_STREAM_WAIT (
    pt,
    stream
) `PT_WAIT_UNTIL (pt, syn_stream_readable (stream))`

Yields the protothread until syn_stream_readable() returns true.

Parameters:

pt Protothread context.
stream Pointer to SYN_Stream.

The documentation for this class was generated from the following file src/syntropic/util/syn_stream.h