bus_owner.h File Reference

Explicit bounded multi-producer, single-executor adapter. More...

#include "nexus/core/request.h"
#include "nexus/os/wait.h"

Go to the source code of this file.

Data Structures
struct	nx_owner_guard_port_t
	Explicit bounded metadata exclusion port. More...
struct	nx_owner_executor_port_t
	One real execution owner, injected without OS dependency. More...
struct	nx_owner_ticket_t
	Stable control identity; never dereference a stale request pointer. More...
struct	nx_owner_slot_t
	Exact caller-owned slot, linked in either the free or FIFO chain; initialize only with owner init. More...
struct	nx_bus_owner_t
	Explicit adapter state; external application supplies all storage. More...

Functions
nx_result_t	nx_bus_owner_init (nx_bus_owner_t *owner, nx_owner_slot_t *slots, size_t capacity, nx_owner_guard_port_t guard, nx_owner_executor_port_t executor, nx_clock_t clock, const nx_wait_port_t *wake)
	Initialize unused owner/slot storage.
nx_result_t	nx_bus_owner_submit (nx_bus_owner_t *owner, nx_request_t *request, void *operation, const nx_wait_port_t *completion, nx_owner_ticket_t *ticket)
	Establish the chain's unique admission.
nx_result_t	nx_bus_owner_cancel (nx_bus_owner_t *owner, nx_owner_ticket_t ticket)
	Submit cancellation through stable adapter storage.
nx_result_t	nx_bus_owner_service (nx_bus_owner_t *owner)
	Advance at most one bounded execution step.
void	nx_bus_owner_stop (nx_bus_owner_t *owner)
	Close admission and request every accepted operation to stop.
bool	nx_bus_owner_idle (nx_bus_owner_t *owner)
	Test whether execution and completion publication have exited.

Detailed Description

Explicit bounded multi-producer, single-executor adapter.

Author

Nexus Team

Definition in file bus_owner.h.

Function Documentation

nx_bus_owner_cancel()

nx_result_t nx_bus_owner_cancel	(	nx_bus_owner_t *	owner,
		nx_owner_ticket_t	ticket )

Submit cancellation through stable adapter storage.

Parameters

[in,out]	owner	Live adapter
[in]	ticket	Previously accepted slot/epoch

Returns

SUCCESS when marked, STATE for stale/released identity

Note

Task multi-producer context. No request pointer is accepted. Queued cancellation settles without starting. Active cancellation drains cooperatively; an irreversible operation may already have transferred data.

nx_bus_owner_idle()

bool nx_bus_owner_idle

(

nx_bus_owner_t *

owner

)

Test whether execution and completion publication have exited.

Parameters

[in,out]

owner

Live adapter

Returns

True if no queue/active/service publisher remains

Note

Join producers and any wake publishers before reclaiming owner, slots, guard or notifications. No future submit/cancel is permitted.

nx_bus_owner_init()

nx_result_t nx_bus_owner_init	(	nx_bus_owner_t *	owner,
		nx_owner_slot_t *	slots,
		size_t	capacity,
		nx_owner_guard_port_t	guard,
		nx_owner_executor_port_t	executor,
		nx_clock_t	clock,
		const nx_wait_port_t *	wake )

Initialize unused owner/slot storage.

Parameters

[out]	owner	Unused caller-owned adapter storage
[in]	slots	Exact queue capacity, no maximum pool
[in]	capacity	Number of slots, greater than zero
[in]	guard	Live short exclusion port
[in]	executor	Single real execution port
[in]	clock	Same monotonic domain as request deadlines
[in]	wake	Optional static executor notification, or NULL

Returns

SUCCESS or INVALID

Note

Startup context; no task, worker, timer or heap is created.

nx_bus_owner_service()

nx_result_t nx_bus_owner_service

(

nx_bus_owner_t *

owner

)

Advance at most one bounded execution step.

Parameters

[in,out]

owner

Live adapter, called by its unique executor

Returns

SUCCESS for progress/idle, BUSY for provider wait/contention, or provider error while retaining ownership for continued recovery

Note

Task/explicit loop only. Consumers never service through wait. Keep calling during stop until idle; no callback creates a worker.

nx_bus_owner_stop()

void nx_bus_owner_stop

(

nx_bus_owner_t *

owner

)

Close admission and request every accepted operation to stop.

Parameters

[in,out]

owner

Live adapter

Note

Task context. Executor must keep servicing/draining while producers wait/join. Stop is not settlement or storage reclamation.

nx_bus_owner_submit()

nx_result_t nx_bus_owner_submit	(	nx_bus_owner_t *	owner,
		nx_request_t *	request,
		void *	operation,
		const nx_wait_port_t *	completion,
		nx_owner_ticket_t *	ticket )

Establish the chain's unique admission.

Parameters

[in,out]	owner	Live accepting adapter
[in,out]	request	Prepared READY storage, retained until SETTLED
[in]	operation	Executor-specific descriptor and payload storage
[in]	completion	Optional static caller wake port, or NULL
[out]	ticket	Stable cancellation identity, valid on SUCCESS

Returns

SUCCESS means ACCEPTED; rejection retains zero references

Note

Task multi-producer context. Free-slot admission and FIFO insertion use constant metadata work under the guard. An exhausted epoch permanently retires its slot. Deadline includes queue residence. Caller must not modify request, operation or buffers after admission. A notification error after admission cannot change SUCCESS to rejection; executor must recheck/pump periodically.