stream.c File Reference

Private implementation of the stream port. More...

#include "internal/stream_handle.h"
#include "stream/borrowers/stream.h"
#include "stream/lifecycle/stream_lifecycle.h"
#include "stream/adapters/stream_adapters_api.h"
#include "policy/lexleo_assert.h"

Include dependency graph for stream.c:

Go to the source code of this file.

Functions
size_t	stream_read (stream_t *s, void *buf, size_t n, stream_status_t *st)
	Read bytes from a stream.
size_t	stream_write (stream_t *s, const void *buf, size_t n, stream_status_t *st)
	Write bytes to a stream.
stream_status_t	stream_flush (stream_t *s)
	Flush a stream.
stream_status_t	stream_create (stream_t **out, const stream_vtbl_t *vtbl, void *backend, const stream_env_t *env)
	Create a generic stream handle from adapter-provided backend bindings.
void	stream_destroy (stream_t **s)
	Destroy a stream handle.
const stream_ops_t *	stream_default_ops (void)
	Return the default borrower-facing ops table for the stream port.
stream_env_t	stream_default_env (const osal_mem_ops_t *mem_ops)
	Build a default stream_env_t from injected memory operations.

Function Documentation

stream_create()

stream_status_t stream_create	(	stream_t **	out,
		const stream_vtbl_t *	vtbl,
		void *	backend,
		const stream_env_t *	env
	)

This function is intended to be called by stream adapters to construct a public stream_t from:

• a dispatch table describing backend operations,
• an adapter-owned backend instance,
• an injected environment carrying runtime dependencies.

The produced stream handle takes ownership of neither the vtable nor the environment object itself; it only stores the required runtime references. The backend lifetime and close semantics are governed by the adapter contract, notably through vtbl->close.

Parameters

[out]	out	Receives the created stream handle. Must not be NULL.
[in]	vtbl	Backend dispatch table. Must not be NULL and must provide non-NULL operations.
[in]	backend	Adapter-owned backend instance to bind to the stream. May be NULL only if the resulting semantics are explicitly supported by the caller, though normal adapters are expected to provide a valid backend.
[in]	env	Stream environment carrying injected runtime dependencies. Must not be NULL.

Returns

• STREAM_STATUS_OK on success
• STREAM_STATUS_INVALID if arguments are invalid
• STREAM_STATUS_OOM on allocation failure

Postcondition

On success, *out contains a valid stream handle that must later be destroyed via stream_destroy().

Definition at line 69 of file stream.c.

stream_default_env()

stream_env_t stream_default_env

(

const osal_mem_ops_t *

mem_ops

)

Parameters

[in]

mem_ops

Memory operations to expose through the returned environment.

Returns

A stream_env_t such that ret.mem == mem_ops.

Note

This helper does not allocate and performs no validation. It only packages the provided dependency into a public stream_env_t.

Definition at line 132 of file stream.c.

stream_default_ops()

const stream_ops_t * stream_default_ops

(

void

)

The returned table exposes the default public borrower operations of the stream port.

Returns

Non-NULL pointer to a well-formed stream_ops_t.

Postcondition

• ret->read != NULL
• ret->write != NULL
• ret->flush != NULL

Definition at line 123 of file stream.c.

stream_destroy()

void stream_destroy

(

stream_t **

s

)

Parameters

[in,out]

s

Address of the stream handle to destroy.

If s == NULL or *s == NULL, this function does nothing. Otherwise, it releases the stream object and sets *s to NULL.

Definition at line 98 of file stream.c.

stream_flush()

stream_status_t stream_flush

(

stream_t *

s

)

Parameters

[in]

s

Stream handle to flush.

Returns

Operation status.

This function exposes the borrower-facing flush operation of the stream port.

Definition at line 62 of file stream.c.

stream_read()

size_t stream_read	(	stream_t *	s,
		void *	buf,
		size_t	n,
		stream_status_t *	st
	)

Parameters

[in]	s	Stream handle to read from.
[out]	buf	Destination buffer receiving up to n bytes.
[in]	n	Maximum number of bytes to read.
[out]	st	Optional status output.

Returns

Number of bytes actually read.

This function exposes the borrower-facing read operation of the stream port.

If n == 0, the function returns 0 and, when st != NULL, reports STREAM_STATUS_OK.

Definition at line 19 of file stream.c.

stream_write()

size_t stream_write	(	stream_t *	s,
		const void *	buf,
		size_t	n,
		stream_status_t *	st
	)

Parameters

[in]	s	Stream handle to write to.
[in]	buf	Source buffer containing up to n bytes to write.
[in]	n	Maximum number of bytes to write.
[out]	st	Optional status output.

Returns

Number of bytes actually written.

This function exposes the borrower-facing write operation of the stream port.

If n == 0, the function returns 0 and, when st != NULL, reports STREAM_STATUS_OK.

Definition at line 38 of file stream.c.