Shared per-dispatch scratch arena (Layer 5, session-scoped memory). More...

#include "ServerConfig.h"
#include <stddef.h>

Classes
class	ScratchScope
	RAII scope guard for transient scratch borrows. More...

Functions
void *	scratch_alloc (size_t n, size_t align)
	Borrow `n` bytes of scratch, aligned to `align`.

void	scratch_reset (void)
	Reclaim the whole arena (empties it).

size_t	scratch_mark (void)
	Capture the current arena offset (a savepoint for scratch_release()).

void	scratch_release (size_t mark)
	Reclaim everything allocated since `mark` (LIFO).

size_t	scratch_used (void)
	Bytes currently handed out (0 immediately after a reset).

size_t	scratch_high_water (void)
	Largest scratch_used() value seen since boot (for sizing the arena).

size_t	scratch_capacity (void)
	Total arena capacity in bytes (DETWS_SCRATCH_ARENA_SIZE).

Detailed Description

Shared per-dispatch scratch arena (Layer 5, session-scoped memory).

One fixed BSS arena that codec / protocol handlers borrow transient working memory from, instead of each feature carrying its own dedicated scratch buffer. Many such buffers are mutually exclusive in time - a connection is doing HTTP or WebSocket or SSH at any instant, and the session layer runs one event to completion before the next - so overlapping them in a single arena cuts peak DRAM without weakening the zero-heap / deterministic guarantee (fixed size, no runtime growth).

Model - region reset per dispatch. scratch_alloc() bump-allocates from the arena; scratch_reset() empties it in O(1). server_tick() calls scratch_reset() at the top of every event dispatch, so a borrow is valid only until the handler returns. There is no per-allocation free - the whole arena is reclaimed at once.

Race-safety. All codec / protocol logic runs only in the single loop task (server_tick() / handle()); the lwIP callbacks run in tcpip_thread and only fill the rx ring + enqueue events - they never borrow scratch. The arena therefore has exactly one accessor and needs no lock. In debug builds an owner-task assertion (xTaskGetCurrentTaskHandle) fails loud the instant any other context calls in, turning a future mistake into an immediate visible failure instead of a silent cross-core race.

Exhaustion-safety. Borrows live only within one dispatch and are auto-reclaimed by the reset, so a forgotten free cannot accumulate (no creeping exhaustion). An over-budget scratch_alloc() returns nullptr; every caller must take a defined fail-closed path (drop the optional optimization, close the connection, answer 503) and must never dereference a null borrow.

No implicit zeroing. scratch_alloc() returns uninitialized memory and the reset does not wipe; a security-sensitive tenant must wipe its own region after use (as the SSH crypto scratch already does).

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file scratch.h.

Function Documentation

◆ scratch_alloc()

void * scratch_alloc	(	size_t	n,
		size_t	align
	)

Borrow n bytes of scratch, aligned to align.

The returned pointer is valid only until the next scratch_reset() (i.e. only within the current session dispatch). Returns nullptr if the request does not fit the remaining arena - callers MUST handle null and fail closed.

Parameters

n	bytes requested (0 yields a valid non-null pointer when space remains).
align	required alignment in bytes, a power of two (0 selects the platform default).

Returns: pointer to n writable bytes, or nullptr if it does not fit.

Definition at line 85 of file scratch.cpp.

References DETWS_SCRATCH_ARENA_SIZE.

Referenced by ssh_conn_close_channel(), ssh_conn_open_forwarded(), ssh_conn_send(), ssh_pkt_recv(), ssh_pkt_send(), and ws_send_frame().

◆ scratch_reset()

void scratch_reset ( void )

Reclaim the whole arena (empties it).

Called by server_tick() before each event dispatch. Invalidates every pointer previously returned by scratch_alloc().

Definition at line 110 of file scratch.cpp.

◆ scratch_mark()

size_t scratch_mark ( void )

Capture the current arena offset (a savepoint for scratch_release()).

Returns: an opaque mark to pass to scratch_release().

Definition at line 117 of file scratch.cpp.

◆ scratch_release()

void scratch_release ( size_t mark )

Reclaim everything allocated since mark (LIFO).

Restores the arena to a previous scratch_mark(), freeing every scratch_alloc() made in between. Marks must be released in reverse order (nested scopes). Use ScratchScope for return-safe scoping.

Parameters

mark	a value previously returned by scratch_mark() (must be <= the current offset).

Definition at line 124 of file scratch.cpp.

Referenced by ScratchScope::~ScratchScope().

◆ scratch_used()

size_t scratch_used ( void )

Bytes currently handed out (0 immediately after a reset).

Definition at line 132 of file scratch.cpp.

◆ scratch_high_water()

size_t scratch_high_water ( void )

Largest scratch_used() value seen since boot (for sizing the arena).

Definition at line 137 of file scratch.cpp.

References DETWS_WORKER_COUNT.

◆ scratch_capacity()

size_t scratch_capacity ( void )

Total arena capacity in bytes (DETWS_SCRATCH_ARENA_SIZE).

Definition at line 147 of file scratch.cpp.