Explicit POSIX notification, queue and task storage. More...

#include "nexus/os/wait.h"
#include <pthread.h>
#include <stddef.h>

Data Structures
struct	nx_native_notify_t
	Single waiter, multiple task publishers; fields are private. More...
struct	nx_native_queue_t
	Caller-sized queue storage; no heap or global object pool. More...
struct	nx_native_task_t
	Explicit task handle; stack storage is supplied at start. More...

Functions
uint64_t	nx_native_now_us (void)
	Read POSIX monotonic microseconds.
nx_result_t	nx_native_notify_init (nx_native_notify_t *notification)
	Initialize a notification in unused caller storage.
nx_wait_port_t	nx_native_notify_port (nx_native_notify_t *notification)
	Bind a single-waiter latched notification port.
nx_result_t	nx_native_notify_destroy (nx_native_notify_t *notification)
	Destroy after external publisher quiescence.
nx_result_t	nx_native_queue_init (nx_native_queue_t queue, void storage, size_t storage_bytes, size_t depth, size_t item_size)
	Initialize an explicit bounded byte-copy queue.
nx_result_t	nx_native_queue_send (nx_native_queue_t queue, const void item, uint64_t deadline_us)
	Copy one item to the queue.
nx_result_t	nx_native_queue_receive (nx_native_queue_t queue, void item, uint64_t deadline_us)
	Receive one item; closed queues can still be drained.
nx_result_t	nx_native_queue_close (nx_native_queue_t *queue)
	Reject sends and wake all waiting callers.
nx_result_t	nx_native_queue_destroy (nx_native_queue_t *queue)
	Destroy quiesced and drained queue storage.
nx_result_t	nx_native_task_start (nx_native_task_t task, void stack, size_t stack_bytes, void(entry)(void ), void *context)
	Start a task using the supplied host stack.
nx_result_t	nx_native_task_join (nx_native_task_t *task)
	Join after requesting cooperative application stop.

Detailed Description

Explicit POSIX notification, queue and task storage.

Author: Nexus Team

Definition in file native.h.

Function Documentation

◆ nx_native_notify_destroy()

nx_result_t nx_native_notify_destroy ( nx_native_notify_t * notification )

Destroy after external publisher quiescence.

Parameters

[in,out] notification Live storage with no future publishers

Returns: NX_SUCCESS or BUSY when a waiter is still registered

Note: Stop and join publishers first. The check cannot authorize a future call to race destruction. No storage access is allowed afterward.

◆ nx_native_notify_init()

nx_result_t nx_native_notify_init ( nx_native_notify_t * notification )

Initialize a notification in unused caller storage.

Parameters

[out] notification Storage kept alive through all publishers

Returns: NX_SUCCESS or an initialization error

Note: Task context; POSIX signal handlers are unsupported.

◆ nx_native_notify_port()

nx_wait_port_t nx_native_notify_port ( nx_native_notify_t * notification )

Bind a single-waiter latched notification port.

Parameters

[in] notification Initialized storage

Returns: Port using CLOCK_MONOTONIC absolute microseconds and NX_DEADLINE_NEVER for untimed waiting

◆ nx_native_now_us()

uint64_t nx_native_now_us ( void )

Read POSIX monotonic microseconds.

Returns: Clock value; clock_gettime failure is process-fatal

◆ nx_native_queue_close()

nx_result_t nx_native_queue_close ( nx_native_queue_t * queue )

Reject sends and wake all waiting callers.

Parameters

[in,out] queue Live queue

Returns: NX_SUCCESS or invalid error

Note: Task context; caller must join queue users before destroy.

◆ nx_native_queue_destroy()

nx_result_t nx_native_queue_destroy ( nx_native_queue_t * queue )

Destroy quiesced and drained queue storage.

Parameters

[in,out] queue Closed queue, no future users

Returns: NX_SUCCESS or BUSY if users/items remain

◆ nx_native_queue_init()

nx_result_t nx_native_queue_init	(	nx_native_queue_t *	queue,
		void *	storage,
		size_t	storage_bytes,
		size_t	depth,
		size_t	item_size )

Initialize an explicit bounded byte-copy queue.

Parameters

[out]	queue	Unused caller storage
[in]	storage	Caller-owned byte buffer
[in]	storage_bytes	Actual byte capacity
[in]	depth	Number of items, greater than zero
[in]	item_size	Bytes per item, greater than zero

Returns: NX_SUCCESS or invalid/initialization error

Note: Task context; caller keeps buffer until successful destroy.

◆ nx_native_queue_receive()

nx_result_t nx_native_queue_receive	(	nx_native_queue_t *	queue,
		void *	item,
		uint64_t	deadline_us )

Receive one item; closed queues can still be drained.

Parameters

[in,out]	queue	Live queue
[out]	item	At least item_size bytes; valid only on SUCCESS
[in]	deadline_us	Absolute CLOCK_MONOTONIC deadline or NX_DEADLINE_NEVER

Returns: SUCCESS, TIMEOUT, STATE (closed) or error

Note: An immediately available item can be received at an expired deadline. On failure the output is unchanged. Closed queues return STATE only after existing items have been drained.

◆ nx_native_queue_send()

nx_result_t nx_native_queue_send	(	nx_native_queue_t *	queue,
		const void *	item,
		uint64_t	deadline_us )

Copy one item to the queue.

Parameters

[in,out]	queue	Live queue
[in]	item	At least item_size bytes, borrowed during call only
[in]	deadline_us	Absolute CLOCK_MONOTONIC deadline or NX_DEADLINE_NEVER

Returns: SUCCESS, TIMEOUT, STATE (closed) or error

Note: Immediately available capacity is used even at an expired deadline. A finite deadline bounds waiting; spurious wakes never restart its budget. No item is retained on failure.

◆ nx_native_task_join()

nx_result_t nx_native_task_join ( nx_native_task_t * task )

Join after requesting cooperative application stop.

Parameters

[in,out] task Started task; caller must not be the joined task

Returns: NX_SUCCESS only after pthread_join confirms execution exit

Note: May block until entry returns. No forced cancellation. Caller may release context, handle and stack only after success. One external owner serializes start/join; multiple simultaneous joiners and external pthread_cancel/detach are unsupported. Stop/join publishers before destroying their notification or queue storage.

◆ nx_native_task_start()

nx_result_t nx_native_task_start	(	nx_native_task_t *	task,
		void *	stack,
		size_t	stack_bytes,
		void(*	entry )(void *),
		void *	context )

Start a task using the supplied host stack.

Parameters

[out]	task	Zero-initialized unused caller handle
[in]	stack	Aligned storage accepted by pthread_attr_setstack
[in]	stack_bytes	Host stack size, at least PTHREAD_STACK_MIN
[in]	entry	Returning bounded application entry
[in]	context	Entry context, kept alive until join

Returns: NX_SUCCESS or invalid/start error

Note: Task context. No default task, pool or hidden stack exists. POSIX library bookkeeping is host-runtime allocation, not MCU RAM evidence.

Data Structures

Functions

Detailed Description

Function Documentation

◆ nx_native_notify_destroy()

◆ nx_native_notify_init()

◆ nx_native_notify_port()

◆ nx_native_now_us()

◆ nx_native_queue_close()

◆ nx_native_queue_destroy()

◆ nx_native_queue_init()

◆ nx_native_queue_receive()

◆ nx_native_queue_send()

◆ nx_native_task_join()

◆ nx_native_task_start()