vl_stream.c File Reference

#include <stdlib.h>
#include <vl/vl_stream.h>

Include dependency graph for vl_stream.c:

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

Function Documentation

vlStreamDelete()

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()

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_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_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()

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_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()

void vlStreamSetClose	(	vl_stream *	stream,
		vl_stream_func_close	func
	)

Here is the caller graph for this function:

vlStreamSetFlush()

void vlStreamSetFlush	(	vl_stream *	stream,
		vl_stream_func_flush	func
	)

vlStreamSetRead()

void vlStreamSetRead	(	vl_stream *	stream,
		vl_stream_func_read	func
	)

Here is the caller graph for this function:

vlStreamSetSeek()

void vlStreamSetSeek	(	vl_stream *	stream,
		vl_stream_func_seek	func
	)

Here is the caller graph for this function:

vlStreamSetTell()

void vlStreamSetTell	(	vl_stream *	stream,
		vl_stream_func_tell	func
	)

Here is the caller graph for this function:

vlStreamSetWrite()

void vlStreamSetWrite	(	vl_stream *	stream,
		vl_stream_func_write	func
	)

Here is the caller graph for this function:

vlStreamTell()

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_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: