Keyronex Keyronex manual pages

KE_WAIT(9) Kernel Developer's Manual KE_WAIT(9)

ke_wait, ke_wait_multi — dispatcher object waiting mechanism

#include <kdk/kern.h>

kwaitstatus_t
ke_wait(void *object, const char *reason, bool user, bool alertable, nanosecs_t timeout);

kwaitstatus_t
ke_wait_multi(size_t nobjects, void *objects[], const char *reason, bool wait_all, bool user, bool alertable, nanosecs_t timeout, kwaitblock_t *waitblocks);

Dispatcher objects are a set of objects provided by the kernel that can be waited on by a thread. Objects are associated with a signal state; when the object is signalled, it can be acquired by a waiter.

Acquisition may have side effects depending on which object is being waited on; for example, when a wait for a mutex is satisfied, the mutex is then owned by the waiting thread.

The () function waits on a single dispatcher object, while the () function waits on multiple dispatcher objects - either until all of them bcome signalled and all acquired, or until any one of them becomes signalled and is acquired.

If none of the objects is signalled or (for wait-all) all of the objects are not signalled at the time of calling the wait function, the waiting thread is put to sleep until such time as the object(s) become signalled and the wait can be satisfied.

The object types that can be waited on are as follows:

kevent_t
An event object. See kevent(9).
kmutex_t
A mutex object. See kmutex(9).
ksemaphore_t
A semaphore object. See ksemaphore(9).
ktimer_t
A timer object. See ktimer(9).

The parameter object or objects specifies the object(s) to wait on.

The parameter reason specifies a string that describes the reason for waiting, for debugging purposes.

The parameter wait_all specifies whether the wait should be satisfied only when all objects are signalled and acquired. Otherwise, the wait is satisfied when any one of the objects is signalled and acquired.

The parameter user specifies whether the wait is being performed on behalf of a user thread.

The parameter alertable specifies whether the wait can be interrupted by an alert, signal, or AST.

The parameter timeout specifies the maximum time to wait for the object(s) to become signalled, in nanoseconds, before returning unsatisfied.

For waits on greater than 4 objects, the parameter waitblocks should point to an array of wait blocks, one for each object being waited on. These do not need to be initialised.

These functions may only be called from thread context at ipl(9) less than kIPLDPC.

On success, the index of the object that was signalled is returned. For ke_wait(), which takes only one argument, this is always 0.

Otherwise, a negative code is returned. These codes are:

The wait timed out. No objects have been acquired.
The wait was interrupted by an alert, signal, or AST.
An invalid argument was passed to the function.

These functions are implemented in kernel/kern/wait.c.

The interface is declared in kernel/include/kdk/kern.h.

kevent(9), kmutex(9), ksemaphore(9), ktimer(9)

These interfaces have always been in Keyronex.

October 6, 2024 Debian