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

FreeBSD Manual Pages

  
 
  

home | help 
AG_EVENTLOOP(3)		 BSD 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.  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 gov-
     erned 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	asso-
     ciated 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 ar-
     gument 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 struc-
     ture.  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 in-
     voked once	at the start of	AG_EventLoop().	 AG_AddEventEpilogue() regis-
     ters a callback routine to	be invoked on exit, before AG_EventLoop() re-
     turns.  AG_DelEventEpilogue() and AG_DelEventPrologue() destroy the spec-
     ified 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 ap-
     peared in Agar 1.5.0.

BSD				April 14, 2014				   BSD
NAME | SYNOPSIS | DESCRIPTION | MAIN INTERFACE | EVENT SINKS | FILESYSTEM EVENTS | PROCESS EVENTS | 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+13.0-RELEASE+and+Ports>

home | help