****************************************************************************** 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.4: Fix in output_async_descr for large streams - 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.3.tar.gz [2] see http://www.ocaml-programming.de/packages/documentation/equeue/users-guide/ [3] see mailto:gerd@gerd-stolpmann.de