diagnostic.h File Reference

Bounded diagnostics with explicit caller-owned ring storage. More...

#include "nexus/core/status.h"
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	nx_diagnostic_event_t
	One opaque diagnostic record; interpretation belongs to its owner. More...
struct	nx_diagnostic_ring_t
	Explicit ring state, with no default pool, worker or transport. More...

Functions
nx_result_t	nx_diagnostic_ring_init (nx_diagnostic_ring_t *ring, nx_diagnostic_event_t *events, size_t capacity)
	Initialize unpublished ring and caller-owned entries.
nx_result_t	nx_diagnostic_ring_write (nx_diagnostic_ring_t *ring, const nx_diagnostic_event_t *event)
	Copy one event under a bounded saved interrupt mask.
nx_result_t	nx_diagnostic_ring_read (nx_diagnostic_ring_t *ring, nx_diagnostic_event_t *event)
	Consume one event from caller-owned ring.
nx_result_t	nx_diagnostic_ring_dropped (const nx_diagnostic_ring_t *ring, uint32_t *dropped)
	Snapshot the saturating overflow count.

Detailed Description

Bounded diagnostics with explicit caller-owned ring storage.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Definition in file diagnostic.h.

Function Documentation

nx_diagnostic_ring_dropped()

nx_result_t nx_diagnostic_ring_dropped	(	const nx_diagnostic_ring_t *	ring,
		uint32_t *	dropped )

Snapshot the saturating overflow count.

Parameters

[in]	ring	Initialized ring.
[out]	dropped	Caller-owned result.

Returns

SUCCESS, INVALID or CONTEXT.

Note

Uses the same bounded saved-mask domain as record access.

nx_diagnostic_ring_init()

nx_result_t nx_diagnostic_ring_init	(	nx_diagnostic_ring_t *	ring,
		nx_diagnostic_event_t *	events,
		size_t	capacity )

Initialize unpublished ring and caller-owned entries.

Parameters

[out]	ring	Unused caller-owned state.
[in]	events	Naturally aligned contiguous entry storage.
[in]	capacity	Nonzero storage length, at most UINT32_MAX.

Returns

SUCCESS or INVALID without modifying storage on rejection.

Note

Startup or exclusive lifecycle owner only. Both allocations remain alive until all publishers and readers are stopped. Entries cannot alias ring state or a submitted record.

nx_diagnostic_ring_read()

nx_result_t nx_diagnostic_ring_read	(	nx_diagnostic_ring_t *	ring,
		nx_diagnostic_event_t *	event )

Consume one event from caller-owned ring.

Parameters

[in,out]	ring	Initialized ring with live producers.
[out]	event	Separate caller-owned destination.

Returns

SUCCESS, BUSY when empty, INVALID or CONTEXT.

Note

Same privileged single-CPU domain as write. Failed reads leave destination unchanged. This is diagnostic storage, never a completion queue or application work queue.

nx_diagnostic_ring_write()

nx_result_t nx_diagnostic_ring_write	(	nx_diagnostic_ring_t *	ring,
		const nx_diagnostic_event_t *	event )

Copy one event under a bounded saved interrupt mask.

Parameters

[in,out]	ring	Initialized ring.
[in]	event	Stable record until this call returns.

Returns

SUCCESS, BUSY when full, INVALID or CONTEXT.

Note

Privileged Thread/configurable IRQ on one CPU only. NMI/HardFault, unprivileged, SMP, DMA and other security worlds are excluded. Full rings retain older records and saturate the lost-record counter. No clock callback, OS operation, heap, string formatting or transport is used.