request.h File Reference

Caller-owned admission, borrow, settlement and stable cancellation. More...

#include "nexus/core/time.h"

Go to the source code of this file.

Data Structures
struct	nx_request_t
	Caller-owned request metadata, without payload or callbacks. More...
struct	nx_request_slot_t
	Adapter-owned stable cancellation identity. More...

Enumerations
enum	nx_request_state_t {   NX_REQUEST_READY = 0 , NX_REQUEST_QUEUED , NX_REQUEST_ACTIVE , NX_REQUEST_DRAINING ,   NX_REQUEST_SETTLED , NX_REQUEST_QUARANTINED }
	Request state; only READY and SETTLED have no provider borrow. More...

Functions
void	nx_request_initialize (nx_request_t *request)
	Initialize fresh unborrowed request storage.
nx_result_t	nx_request_prepare (nx_request_t *request, nx_time_us_t deadline)
	Prepare a READY or consumed SETTLED request.
nx_request_state_t	nx_request_state (const nx_request_t *request)
	Read request state with acquire ordering.
nx_result_t	nx_request_admit (nx_request_t *request, nx_request_state_t state)
	Establish the chain's unique admission and provider borrow.
nx_result_t	nx_request_transition (nx_request_t *request, nx_request_state_t state)
	Advance an already admitted request without readmission.
void	nx_request_settle (nx_request_t *request, nx_result_t result, size_t transferred)
	Release-publish SETTLED as the final provider access.
nx_result_t	nx_request_result (const nx_request_t *request, nx_result_t *result, size_t *transferred)
	Copy the unique settled result after acquire publication.
nx_result_t	nx_request_slot_bind (nx_request_slot_t *slot, nx_request_t *request, uint64_t *epoch)
	Bind a stable slot to a new request incarnation.
nx_request_t *	nx_request_slot_lookup (const nx_request_slot_t *slot, uint64_t expected_epoch)
	Resolve cancellation using stable storage before dereference.
nx_result_t	nx_request_slot_release (nx_request_slot_t *slot, uint64_t expected_epoch)
	Drop a slot reference only after settlement and control drain.

Detailed Description

Caller-owned admission, borrow, settlement and stable cancellation.

Author

Nexus Team

Definition in file request.h.

Enumeration Type Documentation

nx_request_state_t

enum nx_request_state_t

Request state; only READY and SETTLED have no provider borrow.

Enumerator
NX_REQUEST_READY
NX_REQUEST_QUEUED
NX_REQUEST_ACTIVE
NX_REQUEST_DRAINING
NX_REQUEST_SETTLED
NX_REQUEST_QUARANTINED

Definition at line 20 of file request.h.

Function Documentation

nx_request_admit()

nx_result_t nx_request_admit	(	nx_request_t *	request,
		nx_request_state_t	state )

Establish the chain's unique admission and provider borrow.

Parameters

[in,out]	request	READY request; caller owns storage until SETTLED.
[in]	state	QUEUED for adapter or ACTIVE for direct provider.

Returns

NX_SUCCESS means ACCEPTED. Any failure means REJECTED with zero retained references, payload access or residual effects.

Note

One serialized execution owner; validate hardware/buffers first. Multi-producer adapters hold their metadata guard across admission; concurrent admissions are unsupported.

nx_request_initialize()

void nx_request_initialize

(

nx_request_t *

request

)

Initialize fresh unborrowed request storage.

Parameters

[out]

request

Fresh storage, not visible to a provider/observer.

Note

Task-only. Never use initialization to revoke a live borrow.

nx_request_prepare()

nx_result_t nx_request_prepare	(	nx_request_t *	request,
		nx_time_us_t	deadline )

Prepare a READY or consumed SETTLED request.

Parameters

[in,out]	request	Storage with no remaining observers or adapter loans.
[in]	deadline	Absolute transfer deadline, including queue time.

Returns

NX_SUCCESS; invalid pointer or borrowed state is rejected.

Note

Single owner, task-only; failure creates no borrow.

nx_request_result()

nx_result_t nx_request_result	(	const nx_request_t *	request,
		nx_result_t *	result,
		size_t *	transferred )

Copy the unique settled result after acquire publication.

Parameters

[in]	request	Live request storage with no concurrent reuse.
[out]	result	Final operation result.
[out]	transferred	Valid byte/sample count.

Returns

NX_SUCCESS, NX_ERROR_BUSY while borrowed or invalid arguments.

nx_request_settle()

void nx_request_settle	(	nx_request_t *	request,
		nx_result_t	result,
		size_t	transferred )

Release-publish SETTLED as the final provider access.

Parameters

[in,out]	request	Borrowed storage after all sources have drained.
[in]	result	Final transfer result, not admission status.
[in]	transferred	Valid transferred bytes/samples.

Note

Detach active/queued references and capture any static wake target first. No hardware/IRQ/deferred observer may access request or payload afterwards. Cancel/timeout alone do not satisfy this requirement. A failed drain stays QUARANTINED.

nx_request_slot_bind()

nx_result_t nx_request_slot_bind	(	nx_request_slot_t *	slot,
		nx_request_t *	request,
		uint64_t *	epoch )

Bind a stable slot to a new request incarnation.

Parameters

[in,out]	slot	Zero-initialized, unbound adapter-owned slot.
[in]	request	Live storage to bind; binding itself is not admission.
[out]	epoch	Nonzero identity for later control commands.

Returns

NX_SUCCESS, BUSY, INVALID or EXHAUSTED; no identity repeats.

nx_request_slot_lookup()

nx_request_t * nx_request_slot_lookup	(	const nx_request_slot_t *	slot,
		uint64_t	expected_epoch )

Resolve cancellation using stable storage before dereference.

Parameters

[in]	slot	Stable slot protected by adapter synchronization.
[in]	expected_epoch	Incarnation named by the command.

Returns

Live request only for a matching bound incarnation; else NULL.

nx_request_slot_release()

nx_result_t nx_request_slot_release	(	nx_request_slot_t *	slot,
		uint64_t	expected_epoch )

Drop a slot reference only after settlement and control drain.

Parameters

[in,out]	slot	Stable slot whose commands/observers have exited.
[in]	expected_epoch	Incarnation to release.

Returns

NX_SUCCESS, STATE for stale identity, BUSY while borrowed.

nx_request_state()

nx_request_state_t nx_request_state

(

const nx_request_t *

request

)

Read request state with acquire ordering.

Parameters

[in]

request

Initialized storage kept alive by the caller.

Returns

Current state, or QUARANTINED for NULL.

Note

Task/IRQ bounded; SETTLED guarantees provider's final access has occurred, not that separate adapter observers exited.

nx_request_transition()

nx_result_t nx_request_transition	(	nx_request_t *	request,
		nx_request_state_t	state )

Advance an already admitted request without readmission.

Parameters

[in,out]	request	Admitted request owned by the executor.
[in]	state	ACTIVE, DRAINING or QUARANTINED.

Returns

NX_SUCCESS or NX_ERROR_STATE for an illegal transition.

Note

Execution owner; short task/IRQ metadata operation.