The event-handle type is the common system data type used for building interoperable subsystem interfaces. It consists of two words, the first being the subsystem identifier, and the second being opaque outside the owning subsystem. The application must use both of these when talking to the event multiplexer, but in other contexts, only the opaque word is necessary, as the identity of the subsystem is implied.

typedef struct {
  unsigned subsysid;
  unsigned opaque;
} _evhandle;

An application can wait on multiple event handles. It does this by first asking the event subsystem to create an internal interest set of application-event handles, which the application subsequently refers to by a 1-word set reference. It can subsequently add/remove event handles to/from the interest set, and ask the event multiplexer to block until one of those events has occurred. These two operations are done atomically through a single SWI, Event​Manager_​Parallel​Wait. When events are offered back, they are all of the same priority level.

Different threads of an application can wait on different interest sets — the application can create as many sets as it needs. Each thread can can only wait directly on one set at a time. However, a set is itself a watchable resource, so it can be added to another set.

An application must associate its own opaque handle, the user reference, with each event handle that it adds to a interest set. It is the return of this opaque handle that indicates to the thread that the event has occurred.

If the resource is released while still in the set, the subsystem must notify the event multiplexer. Most importantly, the subsystem must notify the event multiplexer when the event has actually occurred, and what priority to set it at, or to rescind the event before it is supplied to the application — both of these notifications are simply a change of priority applied to the event handle, with a special null priority meaning that the event is not to be offered to the application. The subsystem may offer an API to allow the applied priority to be set.

An event may be placed in an event group. It will not be offered to the application with events of other groups. Most events will operate in group 0. WIMP events will operate in group 1.

When an event handle becomes part of a thread's interest set, the event multiplexer notifies the owning subsystem. If the handle is dropped from the set, the subsystem is similarly notified. It is similarly notified if the handle is offered back through Event​Manager_​Parallel​Wait.

Suppose that a networking subsystem defines a ?socket? resource, and then certain processes may invoke operations on certain sockets. One operation should be to obtain the ?read handle? of the socket (which exists for the lifetime of the socket).

int sock; // a socket descriptor
_evhandle h = _get_socket_handle(sock, SH_READ);
_set_prio(h, 4); // subsystem-independent

The process then has the right to wait on that handle.

// application-dependent
void user_action(void *);
struct ctxt user_data;

// The handle will be added to interest set on next yield,
// and remains there until the application cancels it or quits.
ref = _watch_handle(h, user_action, &user_data);

The example subsystem may allow the event handle and its associated resource to operate according to one or more patterns, such as ?reactor? and ?proactor?. If it supports more than one, it must provide operations to select the pattern or mode.

In the reactor pattern, when data arrives on the socket, the handle is triggered, and the wait call can return. The application's function therefore looks something like this:

void user_action(void *user_data)
{
  // The handle has been triggered.

  struct ctxt *c = user_data;
  int done = recv(c->sock, buf, max_len);

  // The handle is back in the waiting state.
}

In the proactor pattern, instead of using a separate ?read? call to transfer data from kernel space to user space, the subsystem receives a user-space structure identifying the buffer space to be used directly. The application and the kernel update this structure as data is added to or removed from the buffer.

struct _sockbuf_state state;
_set_socket_proactor_state(sock, SH_READ, &state, sizeof state);

(This operation could also serve as the switch between reactor and proactor modes.)

The application's handler function doesn't perform a read operation any more — that has already been done. It just examines the structure to see how much data the kernel has put in, processes it, and alters the structure to indicate how much was used:

void user_action(void *user_data)
{
  struct ctxt *c = user_data;
  // check c->state
  // process data
  // update c->state
}

Suppose that the application retains its own information about handles being watched. This could include a pointer to associated application data, a function to act on that data if the handle is triggered, and the handle itself. This collection of information could be maintained and accessed through the following functions:

struct _watchrec *_create_watch(_evhandle h,
                                void (*func)(void *), void *ctxt);
_evhandle _destroy_watch(struct _watchrec *);
void _invoke_watch(struct _watchrec *); // call (*func)(ctxt)

A struct _watchrec * pointer would be used as the opaque reference submitted to the event subsystem, to be returned when an event is triggered.

The application also maintains an array of event handles to be newly registered for watching, or to be deregistered. Assuming no more than 20 need to be registered or deregistered at a time (i.e. between each waiting call):

struct _handle_assoc {
  _evhandle sys_h;
  void *usr_ref;
} ev_changes[20];
int num_ev_changes;

Two functions could then be provided to extend the set:

struct _watchrec *_watch_handle(_evhandle h,
                                void (*func)(void *), void *ctxt)
{
  // Choose an unused _handle_assoc structure.
  int idx = num_ev_changes++;

  // Add func and ctxt to a maintained structure.
  struct _watchrec *ref = _create_watch(h, func, ctxt);

  // ...and make usr_ref point to it.
  ev_changes[idx].sys_h = h;
  ev_changes[idx].usr_ref = ref;

  return ref;
}

void _ignore_handle(struct _watchrec *ref)
{
  // Obtain the handle, destroy the application structure,
  // and record the handle in the array.
  ev_changes[num_ev_changes++] = {
    .sys_h = _destroy_watch(ref),
    .usr_ref = 0
  };
}

The arrays are then ready to be submitted to Event​Manager_​Parallel​Wait call:

void _yield(void)
{
  // We will handle at most 40 handles being triggered at once.
  void *usr_ref[40];

  // Pass all ev_changes to kernel.
  int rc;
  _swix(Event​Manager_​Parallel​Wait, _INR(0,3)|_OUT(0),
        sizeof usr_ref / sizeof usr_ref[0], usr_ref,
        num_ev_changes, ev_changes,
        &rc);
  
  // Clear ev_changes array, since we've
  // now dealt with them.
  num_ev_changes = 0;

  // Go through usr_ref[0] to usr_ref[rc - 1], invoking the
  // associated user functions.
  for (int i = 0; i < rc; i++)
    _invoke_watch(usr_ref[i]);
}

The event multiplexer provides a SWI operation that accepts a set of event handles, and then blocks the caller until one or more events have occurred, or until after a specified time.

A SWI is also provided for use by other subsystems to obtain several SVC subroutines to allocate and deallocate handles, adjust their priorities, wait on single events, and signal that an event has occurred.

#include <kernel/events.h>

typedef unsigned _evhandle;
struct _evpair {
  _evhandle sys_h;
  void *usr_ref;
};

A subsystem that has blocking resources, and intends to allow applications to monitor them in parallel with resources belonging to other subsystems, must provide the following SVC routines to the event manager by a call to Event​Manager_​Link.