NAME

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

1. Activity on a socket or file descriptor.
2. Expiration of a timer.
3. Kernel-event notifications (e.g., kqueue(2) events). This includes filesystem events and process monitoring.

If thread support is available, Agar allows multiple instances of AG_EventLoop() running concurrently under different threads.

MAIN INTERFACE

void
AG_Terminate(int exitCode);

void
AG_TerminateEv(AG_Event *event);

The AG_EventLoop() routine blocks the current thread, waiting for low-level events, and processing them. The operation of AG_EventLoop is governed by a set of thread-specific event sinks.

Agar-based libraries such as Agar-GUI will automatically register event sinks as appropriate upon initialization (for example, graphics drivers based on the X Windows system may set up an event sink of type AG_SINK_READ to monitor activity on the X file descriptor). Applications are free to register their own event sinks using AG_AddEventSink().

The AG_Terminate() function requests termination of the event loop associated with the current thread. If the current thread is the main thread, AG_Terminate() will terminate the application with exitCode as return code. The AG_TerminateEv() variant accepts an AG_Event style argument instead of an int for the exit code.

EVENT SINKS

void
AG_DelEventSink(AG_EventSink *sink);

void
AG_DelEventsSinkByIdent(enum ag_event_sink_type type, int ident, Uint flags);

AG_EventSink *
AG_AddEventPrologue(AG_EventSinkFn fn, const char *fnArgs, ...);

AG_EventSink *
AG_AddEventEpilogue(AG_EventSinkFn fn, const char *fnArgs, ...);

AG_EventSink *
AG_AddEventSpinner(AG_EventSinkFn fn, const char *fnArgs, ...);

void
AG_DelEventPrologue(AG_EventSink *sink);

void
AG_DelEventEpilogue(AG_EventSink *sink);

void
AG_DelEventSpinner(AG_EventSink *sink);

The
AG_AddEventSink(); routine creates a new event sink under the current thread, and returns a pointer to a newly-allocated
AG_EventSink structure. The type argument may be one of:

AG_SINK_READ

Data is available for reading on file referenced by ident.

AG_SINK_WRITE

Data is available for writing on file referenced by ident.

AG_SINK_FSEVENT

A filesystem event has occured on the file/directory referenced by ident. The type of event is specified in flags (see FILESYSTEM EVENTS for the accepted flags).

AG_SINK_PROCEVENT

An event has occured on the monitored process ident. The type of event is specified in flags (see PROCESS EVENTS below).

The
AG_DelEventSink(); function destroys the specified event sink. The
AG_DelEventSinksByIdent(); function destroys all event sinks with matching ident and flags.

The
AG_AddEventPrologue(); function registers a callback routine to be invoked once at the start of
AG_EventLoop();.
AG_AddEventEpilogue(); registers a callback routine to be invoked on exit, before
AG_EventLoop(); returns.
AG_DelEventEpilogue(); and
AG_DelEventPrologue(); destroy the specified epilogue/prologue routine.

The
AG_AddEventSpinner(); routine registers a "spinner" callback routine. Spinner routines are invoked repeatedly and unconditionally by
AG_EventLoop();, until the event loop terminates, or
AG_DelEventSpinner(); is invoked.

FILESYSTEM EVENTS

AG_FSEVENT_DELETE

The file has been deleted.

AG_FSEVENT_WRITE

A write has occured on the file.

AG_FSEVENT_EXTEND

The file has been extended in size.

AG_FSEVENT_ATTRIB

File attributes have been changed.

AG_FSEVENT_LINK

The link count on the file has changed.

AG_FSEVENT_RENAME

The referenced file has been renamed.

AG_FSEVENT_REVOKE

Filesystem has unmount, or revoke(2) called.

PROCESS EVENTS

AG_PROCEVENT_EXIT

Monitored process has exited.

AG_PROCEVENT_FORK

Monitored process has called fork(2).

AG_PROCEVENT_EXEC

Monitored process has called exec(3).

SEE ALSO

HISTORY