4.28 Simple event loop (SEL)

The library (vicare posix simple-event-loop) implements an event loop capable of serving: file descriptors, interprocess signals, batch task execution. The library is available if Vicare is configured with the POSIX API enabled. The SEL makes use of the BUB API for interprocess signals.

When importing this library it is suggested to prefix the bindings as follows:

(import (vicare)
  (prefix (vicare posix) px.)
  (prefix (vicare posix simple-event-loop) sel.))

in practice the SEL can be used only along with (vicare posix).

Exceptions raised by registered event handlers are catched with guard and silently discarded; it is our responsibility to handle errors appropriately in the handlers.

Parameter: log-procedure

When set to #t causes debugging messages to be displayed on the current error port. When set to a procedure: such procedure is called with a single argument whenever a log message must be reported; such single argument is a string representing a log line (without terminating newline). When set to #f nothing happens.

Function: initialise

Function: finalise

Initialise or finalise the infrastructure of SEL. Prior to entering the loop we must call initialise.

initialise calls signal-bub-init and finalise calls signal-bub-final from (vicare posix).

Function: do-one-event

Serve all the events associated to pending received interprocess signals, then serve a single event from file descriptors or fragmented tasks. Return #t if one event from file descriptors or fragmented tasks was served, return #f otherwise.

Function: enter

Function: leave-asap

Enter or leave the event loop. enter starts servicing events from the registered event sources, indefinitely until leave-asap is called.

Function: busy?

Return a boolean, #t if at least one event source is registered. In this context: interprocess signals do not count as event source.

Interprocess signals

Function: receive-signal signum handler

Register the thunk handler to be called whenever the signal signum is received. Any number of handlers can be associated to a single signal. Every handler is called once and removed from the loop.

Function: serve-interprocess-signals

Serve all the pending events for received interprocess signals. Return unspecified values.

File descriptor events

SEL can interface with both raw file descriptors and Scheme ports wrapping a file descriptor; other Scheme port types are not supported.

Function: readable port/fd handler

Function: readable port/fd handler expiration-time expiration-handler

Function: writable port/fd handler

Function: writable port/fd handler expiration-time expiration-handler

Function: exception port/fd handler

Function: exception port/fd handler expiration-time expiration-handler

Register the thunk handler to be called whenever the port or file descriptor port/fd becomes readable, writable or receives an exceptional notification. Every handler is called once and removed from the loop.

When expiration-time and expiration-handler are used: expiration-time must be a time struct as defined by the library (vicare); expiration-handler must be a thunk. Whenever the port or file descriptor is queried for events: if the event did not happen and the current time is past the expiration time, the expiration handler is invoked.

Function: forget-fd port/fd

Remove all the registered handlers associated to the port or file descriptor port/fd.

Function: do-one-fd-event

Serve one file descriptor event, if any. Return a boolean, #t if an event was served.

Fragmented tasks

A fragmented task is a thunk performing a portion of a job. If the thunk returns #f: the job is finished. If the thunk returns a procedure: a portion of job was finished and the returned procedure is a thunk to call to execute the next portion.

Function: task-fragment thunk

Register the thunk as fragment of a task. When thunk is evaluated: if its return value is a procedure, that procedure is automatically registered as task fragment.

Function: do-one-task-event

Evaluate one task event, if any. Return a boolean, #t if a task was run.