multiwaiter.h File Reference

This file provides interfaces to the multi-waiter system. More...

#include <compartment.h>
#include <stdlib.h>
#include <timeout.h>

Go to the source code of this file.

Classes
struct	EventWaiterSource
	Structure describing a change to the set of managed event sources for an event waiter. More...

Functions
typedef	CHERI_SEALED (struct MultiWaiterInternal *) MultiWaiter
	Opaque type for multiwaiter objects.
int	multiwaiter_create (TimeoutArgument timeout, AllocatorCapability heapCapability, MultiWaiter *ret, size_t maxItems)
	Create a multiwaiter object.
int	multiwaiter_delete (AllocatorCapability heapCapability, MultiWaiter mw)
	Destroy a multiwaiter object.
int	multiwaiter_wait (TimeoutArgument timeout, MultiWaiter waiter, struct EventWaiterSource *events, size_t newEventsCount)
	Wait for events.

Detailed Description

This file provides interfaces to the multi-waiter system.

A multi-waiter object (or 'multiwaiter') is an object that allows a calling thread to suspend execution until one of a set of events has occurred.

The CHERIoT multiwaiter system is designed to avoid allocation (or interaction with the allocator) on the fast path. The scheduler may not capture any of the arguments to the multiwaiter's wait call and expose them to other threads unless they are heap allocated. It must also be robust in the presence of malicious code that attempts to concurrently mutate any data structures while sleeping.

The multiwaiter object is allocated with space to wait for n objects, up to a fixed limit. Each wait call provides a set of things to wait on and will suspend until either one occurs or a timeout is reached. On return, the caller-provided list will be updated. This list can be allocated on the stack: the scheduler does not need to hold a copy of it between calls or write to it from another thread.

The multiwaiter should be used sparingly. In the worst case, it can add a linear-complexity overhead on all wake events. Memory overhead and code size have been the key optimisation goals for this design. Unlike systems such as kqueue, scalability has not been a priority in this design because expected number of waited objects is small and so is the number of threads.

Definition in file multiwaiter.h.

Function Documentation

CHERI_SEALED()

typedef CHERI_SEALED

(

struct MultiWaiterInternal *

)

Opaque type for multiwaiter objects.

Callers will always see this as a sealed object.

multiwaiter_create()

int multiwaiter_create	(	TimeoutArgument	timeout,
		AllocatorCapability	heapCapability,
		MultiWaiter *	ret,
		size_t	maxItems )

Create a multiwaiter object.

This is a stateful object that can wait on at most maxItems event sources.

References multiwaiter_create().

Referenced by multiwaiter_create().

multiwaiter_wait()

int multiwaiter_wait	(	TimeoutArgument	timeout,
		MultiWaiter	waiter,
		struct EventWaiterSource *	events,
		size_t	newEventsCount )

Wait for events.

The first argument is the multiwaiter to wait on. New events can optionally be added by providing an array of newEventsCount elements as the newEvents argument.

Return values:

• On success, this function returns 0.
• If the arguments are invalid, this function returns -EINVAL.
• If the timeout is reached without any events being triggered then this returns -ETIMEDOUT.

References multiwaiter_wait().

Referenced by multiwaiter_wait().