These are global function pointers, initialized by default to the standard C
library functions malloc, realloc, and free.
Applications using liboop may reset these pointers to allocation and
deallocation routines with a compatible interface; libraries should use
these function pointers wherever possible to allocate and release memory.
These pointers are normally set before calling any liboop code; if they
are changed during operation, the new oop_free and
oop_realloc functions should be
capable of handling memory obtained with the old oop_malloc.
oop_malloc
This function allocates a block of memory of size len and returns
a pointer to the start of the block. If allocation fails, NULL is returned.
This function resizes a block of memory at ptr to have the new
length len. If ptr is NULL, fresh memory is allocated.
If len is zero, memory is freed and NULL is returned.
If ptr is NULL and len is zero, nothing is done and NULL
is returned. If reallocation fails, NULL is returned.
oop_free
This function releases a block of memory, designated by ptr,
previously allocated by oop_malloc. Once released, the memory may
be immediately overwritten, and/or reused by subsequent calls to
oop_malloc.
*Compatibility note: oop_realloc
is only available in version 0.7 or newer.
Liboop is primarily an interface definition. It defines an interface
which components may use to request notification when an event
(activity on a file descriptor, the real-time clock reaches a certain value,
a particular signal is received) occurs. The component which owns the event
loop -- the component whose code is active when the system is idle --
implements the interface; it is an event source. Components which
are interested in events register themselves with the event source; they are
event sinks. Event sinks may themselves source other, higher-level
events, but that is outside liboop's scope.
Control flow.
During initialization, the event source is created. At least one event sink
is also created, and registered with the event source. Once initialization
completes, control is transferred to the event source, which (at its core)
waits for events, usually using a system function like select() or poll().
When an event occurs, the event source gives a callback to all the
event sinks which registered interest in that event.
During callbacks, the event sinks react to the event as appropriate (usually
performing some I/O, or at least modifying internal state). Event sinks for
events which are no longer relevant may be unregistered; new event sinks may
be registered for additional events. Each event sink, when it finishes,
returns a value which tells the event source whether to continue processing
events or whether to terminate.
While the event source must be fully reentrant (registration and deregistration
may, and indeed usually are, performed within the context of an event), event
sinks need not be; no event sink will be called while another event sink is
active.
If no event sink instructs the event source to terminate, the event source
continues waiting for events. Otherwise, the event source returns to its
caller, which usually shuts down the system.
The system event source.
Liboop comes with a single "reference" implementation of an event source.
This event source uses select() to dispatch events. Most programs built
around liboop will probably use the standard system event source; legacy
programs with their own event loop, or programs with specialized needs may
implement their own event source.
Adapters.
Liboop supports adapters to enable legacy components to use the liboop
interface. For example, many widget sets have their own event loop and their
own mechanism for registering callbacks on timeouts and file descriptor
activity; liboop uses source adapters that accept registration,
register corresponding callbacks with the widget set's event loop, and route
events appropriately. Such adapters let general-purpose liboop-based
components work in an application based on that widget set.
Similarly, some components are designed to work in a non-blocking fashion, and
they might be used with a sink adapter to work with liboop. An
asynchronous DNS query package, for example, could work as a liboop sink that
ultimately generates a higher-level "success" or "failure" callback to the
invoking routine.
Code.
Liboop's abstract event source interface is implemented as a structure
containing C function pointers. These functions accept a pointer to the
structure as their first argument; sources are expected to include their
own data (in whatever format) with the core function pointers. Callbacks
are also C function pointers, with "void *" arguments to pass data.
For more about the liboop interface, see the reference.
liboop home
liboop-www/index.html 0000664 0000000 0000000 00000012665 13035253175 0015177 0 ustar 00root root 0000000 0000000
liboop home page
Liboop is a low-level event loop management library for POSIX-based operating
systems. It supports the development of modular, multiplexed applications
which may respond to events from several sources. It replaces the "select()
loop" and allows the registration of event handlers for file and network I/O,
timers and signals. Since processes use these mechanisms for almost all
external communication, liboop can be used as the basis for almost any
application.
Version 1.0.1 released, including a few accumulated bug fixes and
a new function oop_signal_new_flags(), with an additional flags
argument to support use of the SA_RESTART option when signal handlers
are registered.
7 July 2010
Dan Egnor transfers maintainership of liboop to Niels Mller and
Per Cederqvist. The repository is converted to Git. The web pages
are currently available at http://www.lysator.liu.se/liboop/.
27 October 2003
Version 1.0 released. (The number has no special meaning, it's just
the next increment.) The build is little more robust now, and you can enable
and disable specific adapters in the configure script. The ADNS adapter
returns error messages, the GLib adapter works with GLib 2, and there's a
new oop_sys_run_once() function so you can poll an event source.
11 January 2003
Version 0.9 released. A memory leak when creating and destroying the
system event source was fixed, the robustness of signal handling is improved,
and some minor portability problems were fixed.
18 September 2001
Version 0.8 released, including a source adapter
for Tcl/Tk. (0.7 was never
announced.)
Note that while liboop is
covered by the lesser GPL, ADNS is covered by the full GPL,
and therefore any program which uses ADNS with (or without) liboop must
support distribution under the terms of the full GPL.
Version 0.1 released. This is a very, very simple initial release that
should nevertheless work as a functional event loop. No adapters are included
yet. Testing is minimal, but give it a whirl!
The event source to register or unregister the event sink with. This must
be the same event source you got the function pointer from:
"src->on_fd(src,...);".
int fd
The file descriptor to watch (or stop watching).
oop_event event
The kind of activity to watch for (or stop watching for). Must be one of
OOP_READ (triggered when data is available for reading on the specified file
descriptor), OOP_WRITE (triggered when buffer space is available to write on
the specified file descriptor), or OOP_EXCEPTION*
(triggered on any number of "exceptional" events, such as TCP urgent data
or system error).
oop_call_fd *call
The callback function (event sink) to add (or remove).
void *user
User data passed through to the callback function.
Description.
Note that these are not global functions, but function pointers supplied
by the event source (in the oop_source structure) or by the user.
on_fd
After this function is called, whenever the source's event loop detects
the condition indicated by event (OOP_READ, OOP_WRITE, or
OOP_EXCEPTION*) on the file descriptor
fd, it will call the function
call, passing it a pointer to the event source, the file descriptor,
the event type, and the same opaque user pointer passed to on_fd.
This callback will be called repeatedly as long as the condition persists and
it is not deactivated (see below). Only one callback may be registered per
(event,fd) pair.
cancel_fd
Deactivate an event sink callback registered using on_fd (above).
Any callback associated with the (event,fd) pair in question is removed.
oop_call_fd
Called when the event is triggered. Performs a user_specific action.
Should return OOP_CONTINUE if the event loop should continue operating; any
other value (including OOP_HALT) will cause termination of the event loop.
*Compatibility note: OOP_EXCEPTION
is only available in version 0.7 or newer.
The event source to register or unregister the event sink with. This must
be the same event source you got the function pointer from:
"src->on_signal(src,...);".
int sig
The UNIX signal to monitor (SIGINT, SIGHUP, etc.).
oop_call_signal *call
The callback function (event sink) to add (or remove).
void *user
User data passed through to the callback function.
Description.
Note that these are not global functions, but function pointers supplied
by the event source (in the oop_source structure) or by the user.
on_signal
After this function is called, if the signal sig is received,
when the event loop next runs (immediately, if it is currently waiting for
events), the event source will call the function call, passing it a
pointer to the event source, the signal received, and the same opaque
user pointer passed to on_signal. This callback will be called
again if the signal occurs again, but if the signal is received multiple times
in quick succession the event sink may only receive a single callback.
Many callbacks may be registered for the same signal.
cancel_signal
Deactivate an event sink callback registered using on_signal (above). If
the passed sig, call and user match a previously
registered callback, it will be removed; if they match more than one, one of
them will be removed; otherwise, no action is taken.
oop_call_fd
Called when the event is triggered. Performs a user_specific action.
Should return OOP_CONTINUE if the event loop should continue operating; any
other value (including OOP_HALT) will cause termination of the event loop.
#include <oop.h>
#include <sys/time.h>
/* Zero time, for scheduling an event immediately. */
static const struct timeval OOP_TIME_NOW = { 0, 0 };
/* Callback function prototype. */
typedef void *oop_call_time(oop_source *source,struct timeval tv,void *user);
/* Register and unregister time-triggered event sinks. */
void (*on_time)(oop_source *source,struct timeval tv,oop_call_time *call,void *user);
void (*cancel_time)(oop_source *source,struct timeval tv,oop_call_time *call,void *user);
Arguments.
oop_source *source
The event source to register or unregister the event sink with. This must
be the same event source you got the function pointer from:
"src->on_time(src,...);".
struct timeval tv
The time to wait for. OOP_TIME_NOW (or any time in the past) will cause
immediate scheduling.
oop_call_time *call
The callback function (event sink) to add (or remove).
void *user
User data passed through to the callback function.
Description.
Note that these are not global functions, but function pointers supplied
by the event source (in the oop_source structure) or by the user.
on_time
After this function is called, when the event loop is running and the
time tv is reached (or immediately upon entry to the event loop, if
the specified time occurs in the past), the event source will call the function
call, passing it a pointer to the event source, the scheduled time,
and the same opaque user pointer passed to on_time. This callback
will only be called once. Many callbacks may be registered for the same
time.
cancel_time
Deactivate an event sink callback registered using on_time (above). If the
passed tv, call and user match a previously
registered callback, it will be removed; if they match more than one, one of
them will be removed; otherwise, no action is taken.
oop_call_time
Called when the event is triggered. Performs a user_specific action.
Should return OOP_CONTINUE if the event loop should continue operating; any
other value (including OOP_HALT) will cause termination of the event loop.
The event source to use. The adapter will use this event source to wait
asynchronously for network communication.
adns_initflags flags
Any initialization flags used to create the instance of adns. Refer to the
adns documentation for details.
FILE *diag
The file to send adns diagnostics to. Refer to the adns documentation for
details.
oop_adapter_adns *adapter
An adns adapter to delete, with no outstanding
queries.
Description.
oop_adns_new
Create a new liboop adns adapter. This adapter manages an instance of
Ian Jackson's
asychronous DNS resolver and supplies it with events from source.
The adns instance is initialized with the supplied flags and
diag file; refer to the adns documentation for details.
If a malloc failure or other catastrophic system error occurs creating the
adapter, NULL is returned. The caller must handle this failure.
oop_adns_delete
Destroy the liboop adns adapter adns. This frees all resources
associated with the adapter, including the underlying adns instance. Any
callbacks registered with the event source are cancelled. The adapter can have
no active queries when it is deleted.
The answer to the query (status and RR data). Refer to the adns
documentation for details.
const char *owner
The DNS domain name to query.
adns_rrtype type
The DNS Resource Record type to query. Refer to the adns documentation for
the list of valid RR types.
adns_queryflags flags
Flags for the DNS query. Refer to the adns documentation for details.
oop_call_fd *call
The callback function (event sink) to use for reporting query succcess or
failure.
void *user
User data passed through to the callback function.
oop_adns_query *query
The query to cancel.
Description.
oop_adns_submit
This function begins a DNS query using an adns adapter. Most of the
parameters are passed directly to adns. The query will be processed
asynchronously using the event source specified when the adapter was created;
when it completes (successfully or not), the specified callback will be
invoked.
On malloc failure or catastrophic system error, NULL will be returned.
(Simple name resolution errors, such as not finding the name, do not result
in a NULL query; instead, the callback is invoked with an error status.)
The returned pointer is valid (and may be used to cancel the query) until
either the query is cancelled or the callback is invoked (the query
completes).
oop_adns_cancel
Stop processing a query started with oop_adns_submit (above). This must
be called with a non-NULL pointer returned from oop_adns_submit before the
query has completed (and the callback function invoked). Any query may only
be cancelled once. All resources associated with the query will be
released.
oop_adns_call
Called when the query completes, successfully or not. Performs a
user-specific action with the results of the query. All resources associated
with the query will be released before the function is called, except for the
answer structure itself. (The user is responsible for freeing the answer
structure, as per the conventions established by adns. Note that adns does
not use oop_alloc!)
Should return OOP_CONTINUE if the event loop should continue operating;
any other value (including OOP_HALT) will cause termination of the event loop.
Create a liboop source which uses the
GLib
Main Event Loop for events. There is only one such event loop (the
GMainLoop structure really represents a loop context, not a fully independent
event loop), so this function is global. You may call it multiple times; it
will return the same event source, but keep count of the number of users.
Events will be dispatched when the GLib event loop is run, either directly
via g_main_run() or indirectly via gtk_main().
oop_glib_delete
Delete the liboop source created with oop_glib_new(). This decrements the
count of users; when oop_glib_delete has been called as many times as
oop_glib_new, the event source is removed.
oop_glib_return
Since the event source is run by GLib, the main program has no direct way
of retrieving a value returned by an event handler. Instead, when the loop is
terminated, the GLib event loop should return, and the caller can use this
function to request the specific termination code.
This function isn't commonly used. Furthermore, GLib event loop termination
does not currently work. In other words, ignore this for now.
The event source to use. The adapter will use this event source to wait
asynchronously for console input.
Description.
oop_readline_register
Register a liboop source with the
GNU Readline
Library. The adapter responds asynchronously to console input and notifies
Readline when it arrives via rl_callback_read_char(). You should use the
Readline alternate
interface to prompt the user and receive input.
Note well that Readline will
install
its own signal handlers by default. Make sure to disable this behavior
by setting rl_catch_signals to zero if you wish to manage signals with
liboop.
oop_readline_cancel
Unregister liboop with Readline. After this is called,
rl_readback_read_char() will no longer be invoked automatically.
#include <oop.h>
/* Create and destroy a system event source. */
oop_source_sys *oop_sys_new(void);
void oop_sys_delete(oop_source_sys *sys);
Arguments.
oop_source_sys *sys
The event source to deallocate and destroy.
Description.
oop_sys_new
Create a new system event source. The system event source implements the
event source interface and manages a select() loop. Once the system event
source is created, use oop_sys_source() to
access the event source interface (which lets you register event sinks), and
oop_sys_run() or
oop_sys_run_once() to actually process events.
More than one system event source can exist, though it is rarely useful to do
so (since only one may be active at a time).
If a malloc failure occurs creating the system event source, NULL is returned.
It is up to the caller to handle this failure.
oop_sys_delete
Destroy the system event source sys. This frees all resources
associated with the event source. The source cannot have any active callbacks
(event sinks) associated with it.
#include <oop.h>
/* Run the event loop. */
oop_source *oop_sys_run(oop_source_sys *sys);
oop_source *oop_sys_run_once(oop_source_sys *sys);
Arguments.
oop_source_sys *sys
The event source to operate.
Description.
The oop_sys_run() function starts waiting for events registered with the
system event source sys. As events (file descriptor activity, timed
events, and signals) occur, the appropriate event sinks are called. As long
as these callbacks return OOP_CONTINUE, the function continues running and
processing events.
When one of the callbacks returns some other value, oop_sys_run returns this
value. You can use this technique to allow callbacks to return data to the
"owner" of the event loop (the caller of oop_sys_run). You may then decide
whether to restart the event loop (by calling oop_sys_run again) or not.
If an error occurs waiting for events, oop_sys_run returns OOP_ERROR.
If no event sinks are registered (which would lead to an infinite delay),
oop_sys_run returns OOP_CONTINUE.
The oop_sys_run_once() function behaves just like oop_sys_run(), but returns
immediately after processing any pending results. The return values are the
same as oop_sys_run(), except that a return of OOP_CONTINUE does not
necessarily mean that no event sinks are registered.
#include <oop.h>
/* Get the source interface for a system event source. */
oop_source *oop_sys_source(oop_source_sys *sys);
Arguments.
oop_source_sys *sys
The event source from which to fetch the interface.
Description.
This function returns the standard oop_source interface for the
system event source sys. The interface structure returned contains
function pointers for registering and unregistering callbacks with the event
source; you can pass it to modules which simply want an event source, without
needing to know that you use the system event source in particular.
Create a liboop source which uses the
Tcl
event loop for events. There is only one such event loop, so this
function is global. You may call it multiple times; it will return the same
event source, but keep count of the number of users.
Events will be dispatched when the Tcl event loop is run, either directly
via Tcl_DoOneEvent() or indirectly via Tk_MainLoop(). Unfortunately, there
is no way to stop the Tcl event loop, so return values from event handlers
are ignored.
oop_tcl_delete
Delete the liboop source created with oop_tcl_new(). This decrements the
count of users; when oop_tcl_delete has been called as many times as
oop_tcl_new, the event source is removed.
The event source to use. The adapter will use this event source to wait
asynchronously for network communication.
Description.
oop_www_register
Register a liboop source with the
W3C Protocol Library (libwww).
The adapter acts as an event manager for the libwww
HTEvent module,
replacing the
default event
manager; it relies on the supplied source for actual event handling.
Refer to the libwww documentation for the details of its event architecture.
oop_www_cancel
Unregister liboop with libwww. This frees resources associated with the
adapter, and leaves libwww with no event manager. You may use
HTEventInit in the
HTInit module to
reinstate the libwww default event manager. The adapter can have no active
events when it is deleted. (Take care; libwww tends to cache persistent
connections to Web servers, which may cause events to be registered even if
there are no open requests.)
typedef struct oop_source_sys oop_source_sys;
/* Create and destroy a system event source. */
oop_source_sys *oop_sys_new(void); /* returns NULL on failure */
void oop_sys_delete(oop_source_sys *);
/* Run the system event loop. */
void *oop_sys_run(oop_source_sys *);
void *oop_sys_run_once(oop_source_sys *);
/* Get the standard source interface for a system event source. */
oop_source *oop_sys_source(oop_source_sys *);
GLib is copyrighted by Peter Mattis, Spencer Kimball and Josh MacDonald,
and licensed under the terms of the
GNU Library GPL.
#include <glib.h>
#include <oop-glib.h>
/* Create and destroy a liboop GLib adapter. */
oop_source *oop_glib_new();
void oop_glib_delete();
/* Get the value used to terminate the event loop (e.g. OOP_HALT). */
void *oop_glib_return();
#include <HTEvent.h>
#include <oop-www.h>
/* Register a liboop event source as a libwww "event manager". */
void oop_www_register(oop_source *);
/* Unregister the event source, leaving libwww with no event manager.
This function cannot be executed with outstanding event requests. */
void oop_www_cancel();
/* Use libwww for liboop's oop_malloc, oop_realloc, and oop_free.
If you use this, you must call it before any other liboop function! */
void oop_www_memory();
Please note that while the core of liboop is distributed under the
Lesser GPL, Readline is covered by the
full GPL.
#include <oop-rl.h>
/* Use a liboop event source to call rl_callback_read_char().
It is up to you to call rl_callback_handler_install().
Note well that Readline uses malloc(), not oop_malloc(). */
void oop_readline_register(oop_source *);
/* Stop notifying readline of input characters. */
void oop_readline_cancel(oop_source *);
Developers often wish to write applications which serve as a mediator between
several logical interfaces simultaneously; in fact, most applications work
this way. For example, a browser application might wish to maintain a user
interface while also managing a network connection and occasionally exchanging
data with the local filesystem. A server application might be communicating
with several clients at once while also occasionally receiving a signal from
the administrator directing it to reload its configuration. A multiplayer game
might want to maintain several active user interfaces at once.
Furthermore, each of these interfaces may be quite complex, sufficiently so to
merit shared code modules which specialize in managing the interface.
Widget sets deal with the details of the X protocol and graphical user
interface management; "curses" deals with the arcana of character-based
terminals; WWW libraries offer high-level access to whole families of Internet
transfer protocols; standard I/O and database routines manage filesystem data.
However, the existing techniques available for multiplexing interface code are
very poor. Most of these libraries work in "blocking" fashion; once
instructed to complete a task (such as downloading a file, or presenting a
dialog to the user), they do not return until the task is complete (or failed),
even though this may mean waiting an arbitrary amount of time for some external
agent (such as the user or the network) to respond. Some of the better systems
are able to manage several concurrent tasks internally, but cannot work with
other components.
Developers are thus left with several unpalatable choices:
Accept "blocking" operation. User interfaces stop functioning while the
application waits for the network; one network client's access is stalled
while another client performs a transaction. As more data moves from local
storage (where access is fast enough that blocking is acceptable) to
delay-prone networked media, this is becoming less and less acceptable.
Use multiple threads for concurrency. While this is a good solution for
some problems, developers who choose this route must struggle with relatively
immature and unportable threading models, and deal with the many libraries
which are not thread-safe; furthermore, threaded programming requires
thought-intensive and error-prone synchronization.
Use multiple processes ("forking") for concurrency. This can also work,
but requires all communication between modules to use some form of
inter-process communication, which increases complexity and decreases
performance. Forking itself is a slow operation, leading to complex
"pre-forking" schemes for better performance. Worst of all, each process
must somehow multiplex IPC from other processes with whatever I/O task it had
to accomplish in the first place; this brings back the very problem forking
was designed to address.
Attempt to multiplex each library's I/O operations directly in a master
"select loop". This requires the developer to understand intimately the
exact details of each library's I/O interactions, thus breaking modularity,
fostering unhealthy dependency and leading to a single central snarl through
which all I/O must pass.
The paucity of options is reflected in the quality of applications. How many
programs hang unpleasantly while performing simple network operations like
hostname resolution? How many user interfaces are unnecessarily "modal"?
How many simple servers fork for no good reason? How many network applications
simply don't exist because it's so difficult to write them?
The solution.
Liboop offers a single, simple, central event loop. Modules wishing to perform
I/O without blocking request callbacks from the central event
source. These callbacks may be tied to file-descriptor activity, the
system time, or process signals. Liboop is responsible for invoking these
callbacks as appropriate.
With this system, each module "owns" its own I/O; it can perform arbitrarily
complex operations without blocking anything else in the program. But since
callbacks are executed purely sequentially, there is no complex concurrent code
to manage. From the application developer's point of view, working with liboop
is very simple; the developer simply makes calls to libraries which work their
magic and call the application back when they finish. Applications can easily
manage an arbitrary amount of multiplexed I/O operations using as many
interface libraries as they like without blocking.
To work with this system, libraries and applications must be liboop-aware.
Development with legacy code uses adapters which translate the I/O
model of an application or library into liboop's model. This does require
knowledge of the code's I/O structure, but can at least keep the modules in
an application independent of each other.
Why don't you just use (favorite widget set), which lets you register
callbacks on file descriptors and all that good stuff?
Because not everyone might want to be tied to that widget set. In
particular, the developer of a general-purpose I/O library would want to
allow everyone to use it, without requiring a particular widget set.
Liboop lets the library developer write to a standard interface,
which can then be used with most widget sets and other event loops.
Not quite. GLib is a fine implementation of an event loop (with
bells and whistles) that supports some extensibility (such as the ability to
add extra sources). However, I'm doubtful that it extends far enough that
it could run on top of someone else's event loop (such as the Tk event loop).
Furthermore, the GLib event loop doesn't manage signals; synchronous handling
of asynchronous signals is very difficult to do properly and safely in most
existing systems (without kludges like polling).
In any case, we do have a
GLib source adapter so you can use the GLib event loop
with the liboop interface.
How does liboop compare to Niels Provos' libevent?
Like GLib, libevent is a concrete implementation of an event loop, not
an abstract interface for many event loops; also like GLib, libevent does not
manage signals. Libevent is smaller and simpler than either liboop or Glib.
While liboop and GLib are both licensed under the
Lesser GPL, libevent
appears to be licensed under the original BSD license, including the
advertising clause. Note that the advertising clause renders libevent
incompatible with GPL software!
It is entirely possible to imagine a libevent source adapter for liboop.
If anyone is interested in such an adapter, please contact me.
