vl_stream_memory.c File Reference

#include <stdlib.h>
#include <string.h>
#include <vl/vl_buffer.h>
#include <vl/vl_memory.h>
#include <vl/vl_stream_memory.h>

Include dependency graph for vl_stream_memory.c:

Data Structures
struct	vl_stream_ctx_buffer
struct	vl_stream_ctx_mem

Functions
vl_stream *	vlStreamOpenBuffer (vl_buffer *buffer, vl_bool_t takeOwnership)
	Creates a stream that reads/writes to a dynamic vl_buffer.
vl_stream *	vlStreamOpenMemory (const void *memory, vl_memsize_t size)
	Creates a read-only stream from a raw memory block.
vl_stream *	vlStreamOpenMemoryMutable (void *memory, vl_memsize_t size)
	Creates a writable stream from a fixed-size memory block. Writing past the end will fail.

---

Data Structure Documentation

vl_stream_ctx_buffer

struct vl_stream_ctx_buffer

Collaboration diagram for vl_stream_ctx_buffer:

Data Fields
vl_buffer *	buffer
vl_bool_t	ownsBuffer

vl_stream_ctx_mem

struct vl_stream_ctx_mem

Collaboration diagram for vl_stream_ctx_mem:

Data Fields
vl_memsize_t	cursor
vl_bool_t	readOnly
vl_memsize_t	size
vl_uint8_t *	start

Function Documentation

vlStreamOpenBuffer()

vl_stream * vlStreamOpenBuffer	(	vl_buffer *	buffer,
		vl_bool_t	takeOwnership
	)

Creates a stream that reads/writes to a dynamic vl_buffer.

██ ██ ██ █████ ███████ █████ ██████ ███ ██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ███████ ███████ ███████ ██ ███ ██ ██ ██ ███████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ███████ ██ ██ ███████ ██ ██ ██████ ██ ████ ██ ██ ====—: A Data Structure and Algorithms library for C11. :—====

Copyright 2026 Jesse Walker, released under the MIT license. Git Repository: https://github.com/walkerje/veritable_lasagna

Contract

• Ownership: The caller owns the returned vl_stream pointer and is responsible for calling vlStreamDelete. If takeOwnership is VL_TRUE, the stream assumes ownership of the vl_buffer and will delete it (via vlBufferDelete) when the stream is destroyed.
• Lifetime: The stream is valid until its reference count reaches zero. The vl_buffer must remain valid for the duration of the stream's life if takeOwnership is VL_FALSE.
• Thread Safety: Thread-safe (the stream has its own internal mutex).
• Nullability: Returns NULL if buffer is NULL.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: Accessing the vl_buffer directly while it is being managed by a stream from multiple threads without external synchronization.
• Memory Allocation Expectations: Allocates memory for the vl_stream struct, an internal context struct, and synchronization primitives.
• Return-value Semantics: Returns a pointer to the new stream, or NULL if failure.

Parameters

buffer	The buffer to use.
takeOwnership	If VL_TRUE, the stream will delete the buffer when closed.

Returns

A new stream object.

Here is the call graph for this function:

vlStreamOpenMemory()

vl_stream * vlStreamOpenMemory	(	const void *	memory,
		vl_memsize_t	size
	)

Creates a read-only stream from a raw memory block.

Contract

• Ownership: The caller owns the returned vl_stream pointer. The memory block is NOT owned by the stream.
• Lifetime: The stream is valid until its reference count reaches zero. The underlying memory block must remain valid and unchanged for the entire lifetime of the stream.
• Thread Safety: Thread-safe (internal mutex).
• Nullability: Returns NULL if memory is NULL.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: Modifying the underlying memory while the stream is active.
• Memory Allocation Expectations: Allocates memory for the vl_stream struct, an internal context struct, and synchronization primitives.
• Return-value Semantics: Returns a pointer to the new read-only stream, or NULL.

Parameters

memory	Pointer to the data.
size	Size of the data in bytes.

Returns

A new stream object.

vlStreamOpenMemoryMutable()

vl_stream * vlStreamOpenMemoryMutable	(	void *	memory,
		vl_memsize_t	size
	)

Creates a writable stream from a fixed-size memory block. Writing past the end will fail.

Contract

• Ownership: The caller owns the returned vl_stream pointer and the underlying memory block.
• Lifetime: The stream is valid until its reference count reaches zero. The underlying memory block must remain valid for the entire lifetime of the stream.
• Thread Safety: Thread-safe (internal mutex).
• Nullability: Returns NULL if memory is NULL.
• Error Conditions: Returns NULL on allocation failure. Write operations will fail if they exceed the specified size.
• Undefined Behavior: None.
• Memory Allocation Expectations: Allocates memory for the vl_stream struct, an internal context struct, and synchronization primitives.
• Return-value Semantics: Returns a pointer to the new writable stream, or NULL.

Parameters

memory	Pointer to the writable data.
size	Size of the data in bytes.

Returns

A new stream object.