Agar

<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

The AG_EventLoop routine loops, continually checking for low-level events and processing them. The most common type of low-level events are:
  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


int AG_EventLoop (void)

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


AG_EventSink * AG_AddEventSink (enum ag_event_sink_type type, int ident, Uint flags, AG_EventSinkFn fn, const char *fnArgs)

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

Acceptable flags for the AG_SINK_FSEVENT event sink include:
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

Acceptable flags for the AG_SINK_PROCEVENT event sink include:
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

AG_CustomEventLoop(3), AG_Event(3), AG_Intro(3)

HISTORY

The AG_EventLoop call first appeared in Agar 1.0. Event sinks first appeared in Agar 1.5.0.

Csoft.net ElectronTubeStore.com