FreeBSD Manual Pages
AG_EVENTLOOP(3) Library Functions Manual AG_EVENTLOOP(3) NAME AG_EventLoop -- agar low-level event loop SYNOPSIS #include <agar/core.h> DESCRIPTION The AG_EventLoop routine loops, continually checking for low-level events and processing them. Its operation is governed by a registered set of Event Sinks which determine the type of low-level events to mon- itor, and the procedures to invoke in order to handle 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 in- cludes filesystem events and process monitoring. Concurrent instances of AG_EventLoop() are allowed in multithreaded builds. In threaded builds, event sinks are associated with running thread at the time of creation (in thread-local storage). MAIN INTERFACE int AG_EventLoop(void) void AG_Terminate(int exitCode) void AG_TerminateEv(AG_Event *event) AG_EventLoop() blocks the current thread, waiting for low-level events, and processing them until termination is requested. Its operation is governed by the registered set of event sinks. The AG_Terminate() function requests termination of the event loop as- sociated 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 cur- rent 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 occurred on the file/direc- tory referenced by ident. The type of event is specified in flags (see "FILESYSTEM EVENTS" for the accepted flags). AG_SINK_PROCEVENT An event has occurred 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 match- ing 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 rou- tine. 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 The file was written to. AG_FSEVENT_EXTEND The file was 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). EXAMPLES The AG_FileDlg(3) widget uses AG_SINK_FSEVENT to auto-refresh directory listings on platforms that offer filesystem monitoring capabilitie The AG_ConsoleOpenFile(3) feature of AG_Console(3) sets up an event sink of type AG_SINK_READ to monitor changes on a file or stream. The agardb(1) debugger uses AG_SINK_PROCEVENT to monitor events related to processes being debugged. Agar's X11 driver AG_DriverGLX(3) sets up an event sink of type AG_SINK_READ in order to receive events from the X file descriptor: Display *display; static int EventSink(AG_EventSink *es, AG_Event *event) { Display *dpy = AG_PTR(1); while (XPending(dpy)) { /* Process event */ } } AG_AddEventSink(AG_SINK_READ, XConnectionNumber(display), 0, EventSink, "%p", display); SEE ALSO AG_CustomEventLoop(3), AG_Event(3), AG_Intro(3), poll(2), select(2), kqueue(2) HISTORY The AG_EventLoop call first appeared in Agar 1.0. Event sinks first appeared in Agar 1.5.0. Agar 1.7 December 21, 2022 AG_EVENTLOOP(3)
NAME | SYNOPSIS | DESCRIPTION | MAIN INTERFACE | EVENT SINKS | FILESYSTEM EVENTS | PROCESS EVENTS | EXAMPLES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_EventLoop&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>