stream_adapters_api.h File Reference

Adapter-side API for constructing and binding stream_t objects. More...

#include "stream/borrowers/stream_types.h"
#include "stream/adapters/stream_env.h"
#include "policy/lexleo_cstd_types.h"

Include dependency graph for stream_adapters_api.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	stream_vtbl_t
	Adapter dispatch table bound to a stream_t instance. More...

Typedefs
typedef size_t(*	stream_read_fn_t) (void *backend, void *buf, size_t n, stream_status_t *st)
	Backend read operation for a stream adapter.
typedef size_t(*	stream_write_fn_t) (void *backend, const void *buf, size_t n, stream_status_t *st)
	Backend write operation for a stream adapter.
typedef stream_status_t(*	stream_flush_fn_t) (void *backend)
	Backend flush operation for a stream adapter.
typedef stream_status_t(*	stream_close_fn_t) (void *backend)
	Backend close operation for a stream adapter.
typedef struct stream_vtbl_t	stream_vtbl_t

Functions
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.

Detailed Description

This header exposes the adapter-facing contract used to bind a backend implementation to the generic stream_t port.

It defines:

• backend operation function-pointer types,
• the stream_vtbl_t dispatch table,
• the adapter-side constructor helper stream_create().

Typical usage:

• an adapter defines backend operations matching this contract,
• fills a stream_vtbl_t,
• allocates or prepares its backend state,
• calls stream_create() to build the public stream handle.

Definition in file stream_adapters_api.h.

Typedef Documentation

stream_close_fn_t

typedef stream_status_t(* stream_close_fn_t) (void *backend)

Parameters

[in]

backend

Adapter-owned backend instance bound to the stream.

Returns

Operation status.

This function is called by stream_destroy() when destroying the stream handle.

Definition at line 110 of file stream_adapters_api.h.

stream_flush_fn_t

typedef stream_status_t(* stream_flush_fn_t) (void *backend)

Parameters

[in]

backend

Adapter-owned backend instance bound to the stream.

Returns

Operation status.

Definition at line 95 of file stream_adapters_api.h.

stream_read_fn_t

typedef size_t(* stream_read_fn_t) (void *backend, void *buf, size_t n, stream_status_t *st)

Parameters

[in]	backend	Adapter-owned backend instance bound to the stream.
[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.

Definition at line 56 of file stream_adapters_api.h.

stream_vtbl_t

typedef struct stream_vtbl_t stream_vtbl_t

stream_write_fn_t

typedef size_t(* stream_write_fn_t) (void *backend, const void *buf, size_t n, stream_status_t *st)

Parameters

[in]	backend	Adapter-owned backend instance bound to the stream.
[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.

Definition at line 80 of file stream_adapters_api.h.

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.