// Copyright Microsoft and CHERIoT Contributors.
// SPDX-License-Identifier: MIT

#pragma once
/**
 * @file multiwaiter.h
 *
 * 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.
 */
#include <compartment.h>
#include <stdlib.h>
#include <timeout.h>

/**
 * Structure describing a change to the set of managed event sources for an
 * event waiter.
 */
struct EventWaiterSource
{
	/**
	 * A pointer to the event source.  This is the futex that is monitored for
	 * the multiwaiter.
	 */
	void *eventSource;
	/**
	 * Event value.  This field is modified during the wait
	 * call.
	 *
	 * This indicates the value to compare the futex word against.  If they
	 * mismatch, the event fires immediately.
	 *
	 * On return, this is set to 1 if the futex is signaled, 0 otherwise.
	 */
	uint32_t value;
};

/**
 * Opqaue type for multiwaiter objects.  Callers will always see this as a
 * sealed object.
 */
struct MultiWaiter;

/**
 * Create a multiwaiter object.  This is a stateful object that can wait on at
 * most `maxItems` event sources.
 */
[[cheri::interrupt_state(disabled)]] int __cheri_compartment("scheduler")
  multiwaiter_create(Timeout             *timeout,
                     struct SObjStruct   *heapCapability,
                     struct MultiWaiter **ret,
                     size_t               maxItems);

/**
 * Destroy a multiwaiter object.
 */
[[cheri::interrupt_state(disabled)]] int __cheri_compartment("scheduler")
  multiwaiter_delete(struct SObjStruct *heapCapability, struct MultiWaiter *mw);

/**
 * 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 -ETIMEOUT.
 */
[[cheri::interrupt_state(disabled)]] int __cheri_compartment("scheduler")
  multiwaiter_wait(Timeout                  *timeout,
                   struct MultiWaiter       *waiter,
                   struct EventWaiterSource *events,
                   size_t                    newEventsCount);