Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
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 monitor, 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	includes
	  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 associ-
     ated 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 occurred 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 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 matching
     ident and flags.

     The AG_AddEventPrologue() function registers a callback routine to  be  in-
     voked 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  epi-
     logue/prologue routine.

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

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  ap-
     peared in Agar 1.5.0.

Agar 1.7			December 21, 2022		 AG_EVENTLOOP(3)

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+15.1.quarterly>

home | help