fs_stream.c File Reference

fs_stream adapter implementation (OSAL file backend). More...

#include "internal/fs_stream_handle.h"
#include "internal/fs_stream_ctor_ud.h"
#include "fs_stream/cr/fs_stream_cr_api.h"
#include "osal/mem/osal_mem.h"
#include "policy/lexleo_assert.h"

Include dependency graph for fs_stream.c:

Go to the source code of this file.

Functions
static stream_status_t	map_osal_status (osal_file_status_t osal_st)
static size_t	fs_stream_read (void *backend, void *buf, size_t n, stream_status_t *st)
static size_t	fs_stream_write (void *backend, const void *buf, size_t n, stream_status_t *st)
static stream_status_t	fs_stream_flush (void *backend)
static stream_status_t	fs_stream_close (void *backend)
static stream_status_t	create_backend (fs_stream_t **out, const fs_stream_args_t *args, const fs_stream_cfg_t *cfg, const fs_stream_env_t *env)
static void	destroy_backend (fs_stream_t **p)
static void	fs_stream_destroy_ud_ctor (const void *ud, const osal_mem_ops_t *mem)
stream_status_t	fs_stream_create_stream (stream_t **out, const fs_stream_args_t *args, const fs_stream_cfg_t *cfg, const fs_stream_env_t *env)
	Create a file-backed stream instance.
stream_status_t	fs_stream_ctor (const void *ud, const void *args, stream_t **out)
	Factory constructor callback for the fs_stream adapter.
stream_status_t	fs_stream_create_desc (stream_adapter_desc_t *out, stream_key_t key, const fs_stream_cfg_t *cfg, const fs_stream_env_t *env, const osal_mem_ops_t *mem)
	Build an adapter descriptor for registering fs_stream in a factory.
fs_stream_cfg_t	fs_stream_default_cfg (void)
	Return a default configuration for the fs_stream adapter.
fs_stream_env_t	fs_stream_default_env (const osal_file_env_t *file_env, const osal_file_ops_t *file_ops, const stream_env_t *port_env)
	Build a default environment for the fs_stream adapter.

Variables
static const stream_vtbl_t	VTBL

Detailed Description

File-backed stream adapter. This module is a thin wrapper around OSAL file operations.

Definition in file fs_stream.c.

Function Documentation

create_backend()

static stream_status_t create_backend ( fs_stream_t **  out, const fs_stream_args_t *  args, const fs_stream_cfg_t *  cfg, const fs_stream_env_t *  env  )

static

Definition at line 134 of file fs_stream.c.

destroy_backend()

static void destroy_backend ( fs_stream_t **  p )

static

Definition at line 183 of file fs_stream.c.

fs_stream_close()

static stream_status_t fs_stream_close ( void *  backend )

static

Definition at line 109 of file fs_stream.c.

fs_stream_create_desc()

stream_status_t fs_stream_create_desc	(	stream_adapter_desc_t *	out,
		stream_key_t	key,
		const fs_stream_cfg_t *	cfg,
		const fs_stream_env_t *	env,
		const osal_mem_ops_t *	mem
	)

The Composition Root uses this function to build a stream_adapter_desc_t suitable for registration into the stream factory, for example via stream_factory_add_adapter().

Memory policy:

• mem must be the allocator that will later be used to destroy the descriptor-owned user data through ud_dtor.

Parameters

[out]

out

Descriptor to initialize. Must not be NULL.

On failure, if out != NULL, *out is reset to an empty descriptor.

Parameters

[in]	key	Adapter key used by the factory to select this adapter. Must not be NULL and must not be an empty string.
[in]	cfg	Adapter configuration to bind into the descriptor. Must not be NULL.
[in]	env	Adapter environment to bind into the descriptor. Must not be NULL.
[in]	mem	Memory operations used to allocate descriptor-owned user data. Must not be NULL.

Return values

STREAM_STATUS_OK	Descriptor successfully created.
STREAM_STATUS_INVALID	One or more arguments are invalid.
STREAM_STATUS_OOM	Allocation of descriptor-owned user data failed.

Definition at line 256 of file fs_stream.c.

fs_stream_create_stream()

stream_status_t fs_stream_create_stream	(	stream_t **	out,
		const fs_stream_args_t *	args,
		const fs_stream_cfg_t *	cfg,
		const fs_stream_env_t *	env
	)

This function allocates and initializes a public stream_t whose backend is an OSAL file opened according to the parameters provided in fs_stream_args_t.

The underlying OSAL file is opened through the file operations injected in the adapter environment.

Ownership:

• On success, a newly allocated stream is returned in *out.
• The caller becomes responsible for destroying it via stream_destroy().
• On failure, *out is left unchanged.

Parameters

[out]	out	Receives the created stream handle. Must not be NULL.
[in]	args	Creation arguments describing the file to open. Must not be NULL.

Contract:

• args->path must not be NULL and must not be an empty string.
• args->flags must not be zero.

Parameters

[in]	cfg	Adapter configuration. Must not be NULL.
[in]	env	Adapter environment containing injected dependencies. Must not be NULL.

Return values

STREAM_STATUS_OK	Stream successfully created.
STREAM_STATUS_INVALID	One or more arguments are invalid.
STREAM_STATUS_OOM	Memory allocation failed.
STREAM_STATUS_IO_ERROR	The underlying OSAL file operation failed.

Definition at line 208 of file fs_stream.c.

fs_stream_ctor()

stream_status_t fs_stream_ctor	(	const void *	ud,
		const void *	args,
		stream_t **	out
	)

This function implements the stream_ctor_fn_t contract expected by the stream port factory.

The opaque user-data pointer ud is expected to reference a fs_stream_ctor_ud_t structure containing the configuration and environment required to construct the stream instance.

The args parameter is the runtime argument blob supplied by the factory when creating a stream instance. It is expected to point to a const fs_stream_args_t * describing the file to open.

Parameters

[in]

ud

Opaque user data stored in the adapter descriptor.

Expected type:

• const fs_stream_ctor_ud_t *

Parameters

[in]

args

Runtime argument blob supplied by the factory.

Expected type:

• const fs_stream_args_t *

Parameters

[out]

out

Receives the created stream handle.

Returns

• STREAM_STATUS_OK on success
• STREAM_STATUS_INVALID if one or more arguments are invalid
• STREAM_STATUS_OOM on allocation failure
• STREAM_STATUS_IO_ERROR if the underlying OSAL file operation fails

Postcondition

On success, *out receives a newly created stream instance owned by the caller.

On failure, *out is left unchanged.

Definition at line 233 of file fs_stream.c.

fs_stream_default_cfg()

fs_stream_cfg_t fs_stream_default_cfg

(

void

)

This helper provides a value-initialized baseline configuration that the Composition Root may override.

Returns

A well-formed default fs_stream_cfg_t.

Definition at line 294 of file fs_stream.c.

fs_stream_default_env()

fs_stream_env_t fs_stream_default_env	(	const osal_file_env_t *	file_env,
		const osal_file_ops_t *	file_ops,
		const stream_env_t *	port_env
	)

This helper packages borrowed dependencies into a value-initialized fs_stream_env_t.

The returned environment does not take ownership of any pointer passed as argument.

Parameters

[in]	file_env	Borrowed OSAL file environment.
[in]	file_ops	Borrowed OSAL file operations table.
[in]	port_env	Borrowed stream port environment.

Returns

A well-formed fs_stream_env_t aggregating the provided dependencies.

Definition at line 298 of file fs_stream.c.

fs_stream_destroy_ud_ctor()

static void fs_stream_destroy_ud_ctor ( const void *  ud, const osal_mem_ops_t *  mem  )

static

Definition at line 199 of file fs_stream.c.

fs_stream_flush()

static stream_status_t fs_stream_flush ( void *  backend )

static

Definition at line 92 of file fs_stream.c.

fs_stream_read()

static size_t fs_stream_read ( void *  backend, void *  buf, size_t  n, stream_status_t *  st  )

static

Definition at line 42 of file fs_stream.c.

fs_stream_write()

static size_t fs_stream_write ( void *  backend, const void *  buf, size_t  n, stream_status_t *  st  )

static

Definition at line 63 of file fs_stream.c.

map_osal_status()

static stream_status_t map_osal_status ( osal_file_status_t  osal_st )

static

Definition at line 22 of file fs_stream.c.

Variable Documentation

VTBL

const stream_vtbl_t VTBL

static

Initial value:

= {
    .read = fs_stream_read,
    .write = fs_stream_write,
    .flush = fs_stream_flush,
    .close = fs_stream_close
}

Definition at line 127 of file fs_stream.c.