vl_stream.h File Reference

#include <vl/vl_atomic.h>
#include <vl/vl_memory.h>
#include <vl/vl_mutex.h>

Include dependency graph for vl_stream.h:

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

Go to the source code of this file.

Data Structures
struct	vl_stream
	Generic, thread-safe byte stream abstraction. More...

Typedefs
typedef vl_memsize_t(*	vl_stream_func_read) (void *buffer, vl_memsize_t size, void *user)
typedef vl_memsize_t(*	vl_stream_func_write) (const void *buffer, vl_memsize_t size, void *user)
typedef vl_bool_t(*	vl_stream_func_seek) (vl_int64_t offset, vl_stream_origin origin, void *user)
typedef vl_int64_t(*	vl_stream_func_tell) (void *user)
typedef void(*	vl_stream_func_flush) (void *user)
typedef void(*	vl_stream_func_close) (void *user)

Functions
VL_API vl_stream *	vlStreamNew (void *userData)
	Creates a new stream object on the heap.
VL_API void	vlStreamDelete (vl_stream *stream)
	Decrements reference count and potentially deletes the stream.
VL_API void	vlStreamRetain (vl_stream *stream)
	Increments the reference count of the stream.
VL_API void	vlStreamSetRead (vl_stream *stream, vl_stream_func_read func)
VL_API void	vlStreamSetWrite (vl_stream *stream, vl_stream_func_write func)
VL_API void	vlStreamSetSeek (vl_stream *stream, vl_stream_func_seek func)
VL_API void	vlStreamSetTell (vl_stream *stream, vl_stream_func_tell func)
VL_API void	vlStreamSetFlush (vl_stream *stream, vl_stream_func_flush func)
VL_API void	vlStreamSetClose (vl_stream *stream, vl_stream_func_close func)
VL_API vl_memsize_t	vlStreamRead (vl_stream *stream, void *outBuffer, vl_memsize_t outLength)
	Reads data from the stream.
VL_API vl_memsize_t	vlStreamWrite (vl_stream *stream, const void *inBuffer, vl_memsize_t inLength)
	Writes data to the stream.
VL_API vl_bool_t	vlStreamSeek (vl_stream *stream, vl_int64_t offset, vl_stream_origin origin)
	Moves the stream position.
VL_API vl_int64_t	vlStreamTell (vl_stream *stream)
	Returns the current position in the stream.
VL_API void	vlStreamFlush (vl_stream *stream)
	Flushes any buffered data to the underlying device.

---

Data Structure Documentation

vl_stream

struct vl_stream

Generic, thread-safe byte stream abstraction.

A vl_stream represents a sequential byte-oriented data source or sink, such as a file, memory buffer, network socket, or virtual stream. It provides a uniform interface for reading, writing, seeking, and querying position, independent of the underlying storage mechanism.

The stream object itself owns no I/O resources directly. Instead, all actual I/O behavior is delegated to a user-provided function table (v-table), with backend-specific state supplied via the userData pointer.

Thread Safety

All public I/O operations on a vl_stream are serialized via an internal mutex. Concurrent calls from multiple threads are safe but will not execute in parallel. Backend implementations are not required to be reentrant.

Reference counting is atomic and allows streams to be safely shared across subsystems. The stream is destroyed automatically when the reference count reaches zero.

Lifetime and Ownership

The stream object manages its own lifetime but does not assume ownership of userData. When the stream is destroyed, the close callback (if provided) is invoked, and the backend is responsible for releasing any resources associated with userData.

Statistics

The totalRead and totalWritten fields track the total number of bytes successfully read from or written to the stream through this interface. These counters are monotonic and updated atomically.

Streams should be fully configured (v-table set) before being exposed to other threads.

Collaboration diagram for vl_stream:

Data Fields
vl_stream_func_close	close	Closes the stream backend and releases associated resources.
vl_stream_func_flush	flush	Flushes any buffered data to the underlying medium.
vl_mutex	lock	Mutex protecting all I/O operations on this stream.
vl_stream_func_read	read	Reads bytes from the stream into a buffer. Returns the number of bytes actually read.
vl_atomic_ularge_t	refCount	Atomic reference count. When this count reaches zero, the stream is closed and freed.
vl_stream_func_seek	seek	Moves the current stream position.
vl_stream_func_tell	tell	Returns the current stream position, or -1 if unsupported.
vl_atomic_ularge_t	totalRead	Total number of bytes successfully read from the stream.
vl_atomic_ularge_t	totalWritten	Total number of bytes successfully written to the stream.
void *	userData	Backend-specific context pointer. This pointer is passed verbatim to all v-table functions and is managed by the backend implementation.
vl_stream_func_write	write	Writes bytes from a buffer to the stream. Returns the number of bytes actually written.

Typedef Documentation

vl_stream_func_close

typedef void(* vl_stream_func_close) (void *user)

vl_stream_func_flush

typedef void(* vl_stream_func_flush) (void *user)

vl_stream_func_read

typedef vl_memsize_t(* vl_stream_func_read) (void *buffer, vl_memsize_t size, void *user)

vl_stream_func_seek

typedef vl_bool_t(* vl_stream_func_seek) (vl_int64_t offset, vl_stream_origin origin, void *user)

vl_stream_func_tell

typedef vl_int64_t(* vl_stream_func_tell) (void *user)

vl_stream_func_write

typedef vl_memsize_t(* vl_stream_func_write) (const void *buffer, vl_memsize_t size, void *user)

Function Documentation

vlStreamDelete()

VL_API void vlStreamDelete

(

vl_stream *

stream

)

Decrements reference count and potentially deletes the stream.

If the reference count reaches zero, the close callback is invoked, and all associated memory (including the internal mutex and the stream struct itself) is freed.

Contract

• Ownership: Releases the caller's reference. If it's the last reference, all ownership is released.
• Lifetime: The stream pointer becomes invalid if the reference count reaches zero.
• Thread Safety: Thread-safe (uses atomic decrement and CAS loop).
• Nullability: Safe to call with NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: Double deletion beyond the number of retains.
• Memory Allocation Expectations: Deallocates the stream struct and its internal mutex.
• Return-value Semantics: None (void).

Parameters

stream

Pointer to the stream to delete.

Here is the call graph for this function:

vlStreamFlush()

VL_API void vlStreamFlush

(

vl_stream *

stream

)

Flushes any buffered data to the underlying device.

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (serialized via internal mutex).
• Nullability: Safe to call with NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

stream

pointer to the stream.

Here is the call graph for this function:

vlStreamNew()

VL_API vl_stream * vlStreamNew

(

void *

userData

)

Creates a new stream object on the heap.

Contract

• Ownership: The caller owns the returned vl_stream pointer and is responsible for calling vlStreamDelete.
• Lifetime: The stream is valid until its reference count reaches zero via vlStreamDelete.
• Thread Safety: Thread-safe (initializes internal mutex and atomics).
• Nullability: Returns NULL if heap allocation for the stream or its internal mutex fails.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: None.
• Memory Allocation Expectations: Allocates memory for the vl_stream struct and a vl_mutex.
• Return-value Semantics: Returns a pointer to the new stream with an initial reference count of 1, or NULL.

Parameters

userData

pointer to backend-specific context.

Returns

pointer to new stream, or NULL.

Here is the call graph for this function:

Here is the caller graph for this function:

vlStreamRead()

VL_API vl_memsize_t vlStreamRead	(	vl_stream *	stream,
		void *	outBuffer,
		vl_memsize_t	outLength
	)

Reads data from the stream.

Contract

• Ownership: Does not transfer ownership.
• Lifetime: stream and outBuffer must be valid for the duration of the call.
• Thread Safety: Thread-safe (serialized via internal mutex).
• Nullability: Returns 0 if stream, stream->read, or outBuffer is NULL.
• Error Conditions: Returns 0 if no read function is configured.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns the number of bytes successfully read and updates the totalRead counter.

Parameters

stream	pointer to the stream.
outBuffer	pointer to the destination buffer.
outLength	maximum number of bytes to read.

Returns

Number of bytes actually read.

Here is the call graph for this function:

vlStreamRetain()

VL_API void vlStreamRetain

(

vl_stream *

stream

)

Increments the reference count of the stream.

Contract

• Ownership: The caller gains a shared reference to the stream.
• Lifetime: Ensures the stream remains valid until the corresponding vlStreamDelete call.
• Thread Safety: Thread-safe (uses atomic increment).
• Nullability: Safe to call with NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

stream

Pointer to the stream to retain.

Here is the caller graph for this function:

vlStreamSeek()

VL_API vl_bool_t vlStreamSeek	(	vl_stream *	stream,
		vl_int64_t	offset,
		vl_stream_origin	origin
	)

Moves the stream position.

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (serialized via internal mutex).
• Nullability: Returns VL_FALSE if stream is NULL.
• Error Conditions: Returns VL_FALSE if the backend seek function fails or is not provided.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns VL_TRUE if the seek operation was successful, VL_FALSE otherwise.

Parameters

stream	pointer to the stream.
offset	offset relative to the specified origin.
origin	seek origin (beginning, current, or end).

Here is the call graph for this function:

vlStreamSetClose()

VL_API void vlStreamSetClose	(	vl_stream *	stream,
		vl_stream_func_close	func
	)

Here is the caller graph for this function:

vlStreamSetFlush()

VL_API void vlStreamSetFlush	(	vl_stream *	stream,
		vl_stream_func_flush	func
	)

vlStreamSetRead()

VL_API void vlStreamSetRead	(	vl_stream *	stream,
		vl_stream_func_read	func
	)

Here is the caller graph for this function:

vlStreamSetSeek()

VL_API void vlStreamSetSeek	(	vl_stream *	stream,
		vl_stream_func_seek	func
	)

Here is the caller graph for this function:

vlStreamSetTell()

VL_API void vlStreamSetTell	(	vl_stream *	stream,
		vl_stream_func_tell	func
	)

Here is the caller graph for this function:

vlStreamSetWrite()

VL_API void vlStreamSetWrite	(	vl_stream *	stream,
		vl_stream_func_write	func
	)

Here is the caller graph for this function:

vlStreamTell()

VL_API vl_int64_t vlStreamTell

(

vl_stream *

stream

)

Returns the current position in the stream.

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (serialized via internal mutex).
• Nullability: Returns -1 if stream is NULL.
• Error Conditions: Returns -1 if the backend tell function fails or is not provided.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns the current byte offset from the beginning of the stream, or -1 on error.

Parameters

stream

pointer to the stream.

Returns

current byte offset, or -1 on error.

Here is the call graph for this function:

vlStreamWrite()

VL_API vl_memsize_t vlStreamWrite	(	vl_stream *	stream,
		const void *	inBuffer,
		vl_memsize_t	inLength
	)

Writes data to the stream.

Contract

• Ownership: Unchanged.
• Lifetime: stream and inBuffer must be valid.
• Thread Safety: Thread-safe (serialized via internal mutex).
• Nullability: Returns 0 if stream, stream->write, or inBuffer is NULL.
• Error Conditions: Returns 0 if no write function is configured.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns the number of bytes successfully written and updates the totalWritten counter.

Parameters

stream	pointer to the stream.
inBuffer	pointer to the source buffer.
inLength	number of bytes to write.

Returns

Number of bytes actually written.

Here is the call graph for this function: