spatium.h File Reference

Spans over a caller's buffer, the two span types, and the spat dispatch table. More...

#include "mmgr.h"

Go to the source code of this file.

Data Structures
struct	mmgr_span
	A buffer being filled: its bytes, how far the writer has gone, and whether it ran out. More...
struct	mmgr_cspan
	A buffer being read: its bytes, how far the reader has gone, and whether it ran out. More...
struct	SpatiumCfg
	Arguments for every spat call, where each call reads only the members it needs. More...
struct	SpatiumNs
	Type of the spat dispatch table. More...

Functions
mmgr_span	mmgr_spat_from (const SpatiumCfg *args)
	Builds a fill span over args->buf, with pos at 0 and overflow clear.
mmgr_cspan	mmgr_spat_cfrom (const SpatiumCfg *args)
	Builds a read span over args->cbuf, with pos at 0 and err clear.
embed_bool	mmgr_spat_ok (const SpatiumCfg *args)
	Returns whether args->span has storage and has not overflowed.
embed_bool	mmgr_spat_cok (const SpatiumCfg *args)
	Returns whether args->cspan has storage and has recorded no error.
embed_bool	mmgr_spat_has_storage (const SpatiumCfg *args)
	Returns whether args->span covers any bytes at all.
void	mmgr_spat_reset (const SpatiumCfg *args)
	Returns the span at args->at to its start and clears its overflow.
mmgr_span	mmgr_spat_after (const SpatiumCfg *args)
	Returns the span beginning args->count bytes into args->span.
mmgr_span	mmgr_spat_first (const SpatiumCfg *args)
	Returns the span covering only the first args->count bytes of args->span.
mmgr_cspan	mmgr_spat_produced (const SpatiumCfg *args)
	Returns a read span over everything written into args->span.
mmgr_cspan	mmgr_spat_read (const SpatiumCfg *args)
	Returns a read span over the first args->count bytes written into args->span.

Variables
static const SpatiumNs	spat
	Dispatch table instance named spat, with each member set to its mmgr_spat_ function.

Detailed Description

Spans over a caller's buffer, the two span types, and the spat dispatch table.

Author

dstroy0 (Douglas Quigg) dquig.nosp@m.g123.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Date

2026-08-29

Note

A span is a region and a cursor into it, with a sticky flag that latches once a walk has run past the end. It carries no storage of its own.

The entries take an argument pack, as every other module's do. A span still travels by value inside that pack. SpatiumCfg holds one instead of pointing at one. A walk cannot change the span it was given.

There are two span types and not one. mmgr_span is written through and latches overflow. mmgr_cspan is read from and latches err. Their extents are named cap and len, and so handing one where the other belongs is a compile error.

The sticky flag makes a span worth passing. A caller may walk one through several steps and test once at the end and not after each.

overflow and err do not mean the same kind of thing. A fill span overruns only when what a writer emits was sized wrong against its buffer, and both of those are settled before the build, and so overflow marks a wrong program. A read span runs out because whatever sent the bytes sent fewer, which is a runtime fact and nothing built wrong.

Definition in file spatium.h.

Function Documentation

mmgr_spat_from()

mmgr_span mmgr_spat_from

(

const SpatiumCfg *

args

)

Builds a fill span over args->buf, with pos at 0 and overflow clear.

Parameters

[in]

args

Buffer buf and its extent cap [BORROWS].

Returns

The span, by value.

Note

Asserts args->buf is not NULL and args->cap is not 0. The default MMGR_ASSERT leaves both unevaluated.

Warning

The span carries args->buf away, so that buffer must outlive every use of the span [BORROWS].

References mmgr_spat_from().

Referenced by mmgr_spat_from().

mmgr_spat_cfrom()

mmgr_cspan mmgr_spat_cfrom

(

const SpatiumCfg *

args

)

Builds a read span over args->cbuf, with pos at 0 and err clear.

Parameters

[in]

args

Buffer cbuf and its extent cap [BORROWS].

Returns

The span, by value.

Note

cbuf and not buf. A buffer that may not be written cannot reach the fill constructor.

Takes cbuf and cap as handed over, with none of the asserts mmgr_spat_from makes. A null cbuf or a zero cap still builds, and mmgr_spat_cok is what reports the span unusable.

Warning

The span carries args->cbuf away, so that buffer must outlive every use of the span [BORROWS].

References mmgr_spat_cfrom().

Referenced by mmgr_spat_cfrom().

mmgr_spat_ok()

embed_bool mmgr_spat_ok

(

const SpatiumCfg *

args

)

Returns whether args->span has storage and has not overflowed.

Parameters

[in]

args

Span to test, as args->span [BORROWS].

Returns

EMBED_TRUE when the span is still usable.

References mmgr_spat_ok().

Referenced by mmgr_spat_ok().

mmgr_spat_cok()

embed_bool mmgr_spat_cok

(

const SpatiumCfg *

args

)

Returns whether args->cspan has storage and has recorded no error.

Parameters

[in]

args

Read span to test, as args->cspan [BORROWS].

Returns

EMBED_TRUE when the span is still usable.

References mmgr_spat_cok().

Referenced by mmgr_spat_cok().

mmgr_spat_has_storage()

embed_bool mmgr_spat_has_storage

(

const SpatiumCfg *

args

)

Returns whether args->span covers any bytes at all.

Parameters

[in]

args

Span to test, as args->span [BORROWS].

Returns

EMBED_TRUE when buf is not NULL and cap is not 0.

References mmgr_spat_has_storage().

Referenced by mmgr_spat_has_storage().

mmgr_spat_reset()

void mmgr_spat_reset

(

const SpatiumCfg *

args

)

Returns the span at args->at to its start and clears its overflow.

Parameters

[in,out]

args

Span to rewind, as args->at [BORROWS].

Note

The one entry that takes a span by pointer, because it is the single one that changes one.

The one call that clears overflow, which is otherwise sticky for the span's whole life.

Warning

args->at is written through with no check of its own, and so it must point at a live span. The const on the pack covers the pack, not the span at the far end of at.

References mmgr_spat_reset().

Referenced by mmgr_spat_reset().

mmgr_spat_after()

mmgr_span mmgr_spat_after

(

const SpatiumCfg *

args

)

Returns the span beginning args->count bytes into args->span.

Parameters

[in]

args

Span to walk, as args->span, and the bytes to skip as args->count [BORROWS].

Returns

A span over what is left, or a failed span when args->count is past cap.

Note

The span that comes back covers the same buffer args->span does [BORROWS]: a second view of those bytes and not a copy. A write through either is seen by both.

An args->count of exactly cap gives an empty span that has not failed: nothing is left, but nothing went wrong either.

References mmgr_spat_after().

Referenced by mmgr_spat_after().

mmgr_spat_first()

mmgr_span mmgr_spat_first

(

const SpatiumCfg *

args

)

Returns the span covering only the first args->count bytes of args->span.

Parameters

[in]

args

Span to narrow, as args->span, and the bytes to keep as args->count [BORROWS].

Returns

A span over those bytes, or a failed span when args->count is past cap.

Note

The span that comes back starts on the same byte args->span starts on [BORROWS], holding a shorter cap over the same storage. A fill through one is read by the other.

References mmgr_spat_first().

Referenced by mmgr_spat_first().

mmgr_spat_produced()

mmgr_cspan mmgr_spat_produced

(

const SpatiumCfg *

args

)

Returns a read span over everything written into args->span.

Parameters

[in]

args

Span to read back, as args->span [BORROWS].

Returns

A read span over its first pos bytes, carrying span's overflow as its err.

Note

The same step as mmgr_spat_read against span's own pos, the case that cannot ask for more than was written and so cannot fail on its own account.

References mmgr_spat_produced().

Referenced by mmgr_spat_produced().

mmgr_spat_read()

mmgr_cspan mmgr_spat_read

(

const SpatiumCfg *

args

)

Returns a read span over the first args->count bytes written into args->span.

Parameters

[in]

args

Span to read back, as args->span, and the bytes to cover as args->count [BORROWS].

Returns

A read span over them, marked err when args->count is past what was written.

Warning

The read span points at the fill span's own bytes [BORROWS], and the const on it binds this view and not the storage. Filling args->span again moves what the reader sees, and so read it back before the next fill or copy the bytes out.

References mmgr_spat_read().

Referenced by mmgr_spat_read().

Variable Documentation

spat

const SpatiumNs spat

static

Dispatch table instance named spat, with each member set to its mmgr_spat_ function.

Definition at line 218 of file spatium.h.