Stream I/O

A sys_iostream_t is a small, fixed set of primitives - peek, read, write, seek, close - implemented differently per backend. More...

Collaboration diagram for Stream I/O:

Macros
#define	SYS_IOSTREAM_CAPACITY   8
	Maximum number of open streams.
#define	SYS_IOSTREAM_EOF   (-1)
	Value returned by sys_iostream_peek() at the end of a stream.

Typedefs
typedef struct sys_iostream_t	sys_iostream_t
	An opaque byte stream. More...
typedef enum sys_iostream_event_t	sys_iostream_event_t
	Stream readiness event flags. More...
typedef void(*	sys_iostream_callback_t) (sys_iostream_t *stream, sys_iostream_event_t events, void *userdata)
	Callback invoked when a stream becomes ready for I/O. More...

Enumerations
enum	sys_iostream_event_t { sys_iostream_event_none = 0, sys_iostream_event_read = 1u, sys_iostream_event_write = 2u }
	Stream readiness event flags. More...

Functions
void	sys_iostream_close (sys_iostream_t *s)
	Release a stream back to the pool. More...
int	sys_iostream_peek (sys_iostream_t *s)
	Look at the next byte without consuming it. More...
size_t	sys_iostream_read (sys_iostream_t *s, char *buf, size_t n)
	Read bytes from a stream. More...
bool	sys_iostream_eof (sys_iostream_t *s)
	Report whether a stream has permanently ended. More...
size_t	sys_iostream_write (sys_iostream_t *s, const char *buf, size_t n)
	Write bytes to a stream. More...
ptrdiff_t	sys_iostream_seek (sys_iostream_t *s, ptrdiff_t offset, bool abs)
	Move a stream's read/write position. More...
bool	sys_iostream_set_callback (sys_iostream_t *stream, sys_iostream_callback_t callback, void *userdata)
	Set a callback for stream readiness events. More...

Detailed Description

A sys_iostream_t is a small, fixed set of primitives - peek, read, write, seek, close - implemented differently per backend.

Instances come from a static pool (SYS_IOSTREAM_CAPACITY), never the heap, and are constructed by a source-specific function rather than directly. String-backed streams come from sys_string_read() and sys_string_open() (sys/string.h). Platform standard streams are exposed through sys_stdin and sys_stdout (sys/stdio.h). A backend can optionally support readiness callbacks through sys_iostream_set_callback(). sys/rune.h's tokenizer and sys/scanner.h's scanner are built entirely on this interface, so other backends can support them without changing their APIs.

Example - read a stream in two passes by seeking back to the start:

sys_iostream_t *s = sys_string_read("hello");

char buf[6] = {0};
sys_iostream_read(s, buf, 5); // buf == "hello"

sys_iostream_seek(s, 0, true); // back to the start
sys_iostream_read(s, buf, 5); // buf == "hello" again

sys_iostream_close(s);

Typedef Documentation

sys_iostream_callback_t

typedef void(* sys_iostream_callback_t) (sys_iostream_t *stream, sys_iostream_event_t events, void *userdata)

Callback invoked when a stream becomes ready for I/O.

Parameters

stream	Stream whose readiness changed.
events	Readiness events that occurred.
userdata	User-defined data pointer provided to sys_iostream_set_callback().

Definition at line 96 of file io.h.

sys_iostream_event_t

typedef enum sys_iostream_event_t sys_iostream_event_t

Stream readiness event flags.

Values may be combined with bitwise OR when registering interest in multiple events.

sys_iostream_t

typedef struct sys_iostream_t sys_iostream_t

An opaque byte stream.

Instances come from a static pool (SYS_IOSTREAM_CAPACITY), with no heap allocation. Streams are constructed by source-specific functions such as sys_string_read() and sys_string_open(), or provided as platform standard streams through sys_stdin and sys_stdout. Release caller-owned streams with sys_iostream_close(); standard streams are released by sys_exit().

Definition at line 70 of file io.h.

Enumeration Type Documentation

sys_iostream_event_t

enum sys_iostream_event_t

Stream readiness event flags.

Values may be combined with bitwise OR when registering interest in multiple events.

Enumerator
sys_iostream_event_none	No event.
sys_iostream_event_read	Data is available to read.
sys_iostream_event_write	The stream can accept output.

Definition at line 79 of file io.h.

                                  {
  sys_iostream_event_none = 0,
  sys_iostream_event_read = 1u,
  sys_iostream_event_write = 2u,
} sys_iostream_event_t;

Function Documentation

sys_iostream_close()

void sys_iostream_close

(

sys_iostream_t *

s

)

Release a stream back to the pool.

Parameters

s	The stream to close, or NULL (a no-op).

Releases any resources the stream's source holds (nothing, for a string-backed stream) and frees its pool slot for reuse.

sys_iostream_eof()

bool sys_iostream_eof

(

sys_iostream_t *

s

)

Report whether a stream has permanently ended.

Parameters

s	The stream to check, or NULL (returns false).

Returns

true if the stream will never produce more data (for example, a network stream whose peer has closed the connection). false if it might still produce more later, or if its backend doesn't distinguish that from "nothing available right now" (the default for any backend that doesn't implement this - a source with no background/async arrival, such as a string or buffer, has no such distinction to make in the first place, since sys_iostream_read() returning 0 already means the same thing there: permanently done).

Not the same question sys_iostream_peek() returning SYS_IOSTREAM_EOF answers - that happens both when a stream is genuinely done and when a live, asynchronously-fed one (a network connection) simply has nothing available yet but is still open, with no way to tell those two apart from that return value alone. sys_iostream_eof() is the explicit version of that question, for a caller that needs to detect a source actually going away rather than just quietly seeing "no data" forever.

sys_iostream_peek()

int sys_iostream_peek

(

sys_iostream_t *

s

)

Look at the next byte without consuming it.

Parameters

s	The stream to peek at.

Returns

The next unread byte, as an unsigned value 0-255, or SYS_IOSTREAM_EOF if the stream is at its end. Calling this repeatedly without an intervening sys_iostream_read() returns the same byte every time.

sys_iostream_read()

size_t sys_iostream_read	(	sys_iostream_t *	s,
		char *	buf,
		size_t	n
	)

Read bytes from a stream.

Parameters

s	The stream to read from.
buf	Destination buffer.
n	Maximum number of bytes to read.

Returns

The number of bytes actually read into buf, which may be less than n. 0 means the stream is at its end - it is not an error.

sys_iostream_seek()

ptrdiff_t sys_iostream_seek	(	sys_iostream_t *	s,
		ptrdiff_t	offset,
		bool	abs
	)

Move a stream's read/write position.

Parameters

s	The stream to seek.
offset	Byte offset - absolute from the start when abs is true (must be >= 0), otherwise relative to the current position (negative moves backward).
abs	true for an absolute seek, false for relative.

Returns

The resulting absolute position (>= 0) on success, or -1 if the seek would go out of bounds - the position is left unchanged in that case.

sys_iostream_set_callback()

bool sys_iostream_set_callback	(	sys_iostream_t *	stream,
		sys_iostream_callback_t	callback,
		void *	userdata
	)

Set a callback for stream readiness events.

Parameters

stream	Stream to observe.
callback	Callback to invoke, or NULL to remove the current callback.
userdata	User-defined data pointer passed to callback.

Returns

true if the callback was registered, false if stream is NULL or its backend does not support readiness notifications.

sys_iostream_write()

size_t sys_iostream_write	(	sys_iostream_t *	s,
		const char *	buf,
		size_t	n
	)

Write bytes to a stream.

Parameters

s	The stream to write to.
buf	Source buffer.
n	Number of bytes to write.

Returns

The number of bytes actually written, which may be less than n (for example if the destination is full). 0 means nothing could be written - for a read-only stream (such as one from sys_string_read()), this is always the case.