******************************************************************************
README - Equeue, event queues for O'Caml
******************************************************************************


==============================================================================
Abstract
==============================================================================

Equeue provides a generic event queue module, and a specific module for file 
descriptor events. Furthermore, this library has been merged with the Shell 
library implementing the invocation of external commands including pipelines 
and redirections. 

Equeue may work stand-alone or in conjunction with labltk, lablgtk, or lablgtk2
, three GUI toolkits into which Equeue can be integrated. 

==============================================================================
Download
==============================================================================

You can download Equeue as gzip'ed tarball [1]. 

==============================================================================
Documentation
==============================================================================

The User's Manual is included in the distribution both as Postscript document 
and bunch of HTML files. An online version can be found here [2]. The User's 
Manual only covers the equeue part of the library, not the shell part. 

The Reference Manuals are included in the distribution only in HTML format. 
However, they are ocamldoc-generated, so it is also possible to read the mli 
sources, and to convert them to other formats that are supported by ocamldoc. 
There are two manuals, one for the equeue part, one for the shell part. 

For a quick introduction into Shell, read the reference page for the Shell 
module, especially the example section.

==============================================================================
Author, Copying
==============================================================================

Equeue has been written by Gerd Stolpmann [3]. You may copy it as you like, you 
may use it even for commercial purposes as long as the license conditions are 
respected, see the file LICENSE coming with the distribution. It allows almost 
everything. 

==============================================================================
Description
==============================================================================

Equeue contains a generic implementation of queues of events of any type, and a 
specific implementation of queues of file descriptor events.

The generic module allows to associate an event queue with an event source, and 
one or several event handlers. The event source generates new events that are 
triggered from the outer world. The handlers consume events, but it is allowed 
that handlers also generate events.

The module for file descriptor events already defines an event source; this 
source watches registered file descriptors and produces events if a descriptor 
wants to deliver data, or if a descriptor is ready to accept data. As in the 
generic module, the handlers consume the events.

The concept of engines is suggested to construct event-driven programs in a 
systematic way. There are already a number of basic engines (polling, copying, 
connecting with a network service, accepting connections, SOCKS), and a number 
of operations for engines (sequential execution, synchronization).  

It is possible to let Equeue cooperate with the event queue implementations of 
Tcl (i.e. labltk) and Glib (i.e. lablgtk or lablgtk2).

The main application of these modules are implementations of protocol stacks 
which can cooperate with each other.

Now, also the Shell library is included in the Equeue distribution. Shell 
provides some of the functionality of a Unix shell; in particular the library 
supports starting simple commands, executing pipelined commands, and arranging 
redirections. For example, it is possible to call a command as a filter, and to 
write data to it while the filtered output is read back.  

The Shell library can be used in conjuction with the event queues. This means 
that there is an engine watching the execution of external commands.

------------------------------------------------------------------------------
Recent Changes
------------------------------------------------------------------------------

-  Changed in 2.1.3: Support for newer versions of lablgtk2. Fix of a file 
   descriptor leak in multi-threaded mode.
   
-  Changed in 2.1.1-2.1.2: Bugfixes in Uq_engines.
   
-  Changed in 2.1: Added support for lablgtk and lablgtk2. At the same time, 
   the interface for the labltk integration changes (read the corresponding 
   chapter in the manual for details).
   Added engine for sending data to file descriptors.
   Added facility to log exceptions caught in critical sections.
   Shell: One can now change the directory when running processes.
   
-  Changed in 2.0.1: Fixed META for shell. Shell_sys catches ESRCH when killing 
   processes.
   
-  Changed in 2.0: Performance improvements for Unixqueue. Introduces the 
   concept of engines. Inclusion of the Shell library.
   
-  Changed in 1.2.2: The TCL extension can be built as shared library when 
   compiled with O'Caml 3.03-alpha.
   
-  Changed in 1.2.1: It is now possible to add events/resources to a system 
   even if the system is currently running in a different thread. If the other 
   thread is blocking, it is waked up and forced to reschedule the system.
   
-  Changed in 1.2: Unixqueue has now an Extra event that can be used for custom 
   events. Several improvements in Unixqueue and Equeue.
   The Unixqueue module is now thread-safe, and the same event system can be 
   safely accessed from several threads.
   There is now a second version of the TCL extension which bases on existing 
   labltk bindings.
   The sources have been reorganized.
   
-  Changed in 1.1.4: Fixed META (only multi-threaded programs are affected)
   
-  Changed in 1.1.3: Upgrade for O'Caml 3. Fixed some errors, too.
   
-  Changed in 1.1.2: Updated URLs in documentation.
   
-  Changed in 1.1.1: Bugfix: The Tcl queue extension did not recognize when new 
   resources were added from a Tcl event handler.
   
-  Changed in 1.1: Bugfix: Interrupted system calls are automatically 
   restarted.
   Enhancement: It is now possible to use Equeue together with Tcl's event 
   queue implementation.
   
-  Changed in 1.0: Many bugfixes. Added code examples. Added a manual. Added 
   support for multi-threaded applications.
   
-  Changed in 0.1.1: The installation of the package is findlib-based.
   

--------------------------

[1]   see http://www.ocaml-programming.de/packages/equeue-2.1.tar.gz

[2]   
      see http://www.ocaml-programming.de/packages/documentation/equeue/users-guide/

[3]   see mailto:gerd@gerd-stolpmann.de



