byte_sequence.h File Reference

Immutable ref-counted byte sequences. More...

Go to the source code of this file.

Data Structures
struct	loomc_byte_sequence_callback_t
	Callback and caller-owned state used to enumerate a sequence. More...

Typedefs
typedef struct loomc_byte_sequence_t	loomc_byte_sequence_t
	Immutable logical sequence of bytes stored in one or more segments.
typedef loomc_status_t(*	loomc_byte_sequence_callback_fn_t) (void *user_data, loomc_byte_span_t segment)
	Callback invoked for each ordered non-empty sequence segment.

Functions
loomc_status_t	loomc_byte_sequence_create_copy (loomc_byte_span_t contents, loomc_allocator_t allocator, loomc_byte_sequence_t **out_sequence)
	Creates a sequence containing a copy of contents.
void	loomc_byte_sequence_retain (loomc_byte_sequence_t *sequence)
	Retains sequence for another owner.
void	loomc_byte_sequence_release (loomc_byte_sequence_t *sequence)
	Releases sequence from one owner.
uint64_t	loomc_byte_sequence_length (const loomc_byte_sequence_t *sequence)
	Returns the logical byte length of sequence.
bool	loomc_byte_sequence_try_get_contiguous_span (const loomc_byte_sequence_t *sequence, loomc_byte_span_t *out_span)
	Attempts to borrow the complete sequence as one contiguous span.
loomc_status_t	loomc_byte_sequence_enumerate (const loomc_byte_sequence_t *sequence, loomc_byte_sequence_callback_t callback)
	Enumerates all non-empty segments in logical byte order.
loomc_status_t	loomc_byte_sequence_clone (const loomc_byte_sequence_t *sequence, loomc_allocator_t allocator, loomc_byte_span_t *out_span)
	Clones sequence into one contiguous allocator-owned span.

Detailed Description

Immutable ref-counted byte sequences.

Byte sequences preserve segmented producer storage across compiler, caching, packaging, and loader boundaries. Segment boundaries are an implementation detail; consumers may enumerate them without allocation or request one explicit contiguous clone when their final API requires it.

Typedef Documentation

loomc_byte_sequence_callback_fn_t

typedef loomc_status_t(* loomc_byte_sequence_callback_fn_t) (void *user_data, loomc_byte_span_t segment)

Callback invoked for each ordered non-empty sequence segment.

segment is borrowed only for the callback duration. Returning a non-OK status stops enumeration and transfers that status to the caller.

loomc_byte_sequence_t

typedef struct loomc_byte_sequence_t loomc_byte_sequence_t

Immutable logical sequence of bytes stored in one or more segments.

A sequence has constant contents and length. Retained handles may be shared across threads and enumerated concurrently.

Function Documentation

loomc_byte_sequence_clone()

loomc_status_t loomc_byte_sequence_clone	(	const loomc_byte_sequence_t *	sequence,
		loomc_allocator_t	allocator,
		loomc_byte_span_t *	out_span )

Clones sequence into one contiguous allocator-owned span.

Parameters

sequence	Sequence to clone.
allocator	Host allocator owning the returned storage.
out_span	Receives the contiguous clone on success.

Returns

OK when the complete sequence was cloned.

The caller frees out_span->data with allocator. Empty sequences return an empty span without allocating. On failure out_span is empty.

loomc_byte_sequence_create_copy()

loomc_status_t loomc_byte_sequence_create_copy	(	loomc_byte_span_t	contents,
		loomc_allocator_t	allocator,
		loomc_byte_sequence_t **	out_sequence )

Creates a sequence containing a copy of contents.

Parameters

contents	Bytes copied into immutable sequence storage.
allocator	Host allocator owning the returned sequence and storage.
out_sequence	Receives one retained sequence on success.

Returns

OK when the sequence was created.

Empty contents produce a real non-NULL empty sequence. The caller releases the returned reference with loomc_byte_sequence_release.

loomc_byte_sequence_enumerate()

loomc_status_t loomc_byte_sequence_enumerate	(	const loomc_byte_sequence_t *	sequence,
		loomc_byte_sequence_callback_t	callback )

Enumerates all non-empty segments in logical byte order.

Parameters

sequence	Sequence to enumerate.
callback	Callback invoked for each segment.

Returns

OK after every segment was visited, or the callback status that stopped enumeration.

loomc_byte_sequence_length()

uint64_t loomc_byte_sequence_length

(

const loomc_byte_sequence_t *

sequence

)

Returns the logical byte length of sequence.

Parameters

sequence

Sequence to inspect, or NULL.

Returns

Sequence length, or zero for a NULL sequence.

loomc_byte_sequence_release()

void loomc_byte_sequence_release

(

loomc_byte_sequence_t *

sequence

)

Releases sequence from one owner.

Passing NULL is allowed.

Parameters

sequence

Sequence to release.

loomc_byte_sequence_retain()

void loomc_byte_sequence_retain

(

loomc_byte_sequence_t *

sequence

)

Retains sequence for another owner.

Passing NULL is allowed.

Parameters

sequence

Sequence to retain.

loomc_byte_sequence_try_get_contiguous_span()

bool loomc_byte_sequence_try_get_contiguous_span	(	const loomc_byte_sequence_t *	sequence,
		loomc_byte_span_t *	out_span )

Attempts to borrow the complete sequence as one contiguous span.

Parameters

sequence	Sequence to inspect.
out_span	Receives the borrowed contiguous span when available.

Returns

True when the producer storage is already contiguous. False leaves out_span empty for a NULL sequence or segmented storage.

The span remains valid while sequence is retained.