----------------------------------------------------------------------------- -- -- Onions Network Streams Library -- http://www.ics.uci.edu/pub/websoft/libwww-ada95/ -- -- R E A D M E -- -- Copyright (C) 1997-1998 Regents of the University of California -- -- Onions is free software; you can redistribute it and/or modify it under -- the terms of the GNU General Public License as published by the Free -- Software Foundation, with or without the single exception listed below; -- either version 2, or (at your option) any later version. Onions is -- distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; -- without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -- PARTICULAR PURPOSE. See the GNU General Public License for more details. -- You should have received a copy of the GNU General Public License -- distributed with Onions; see the file COPYING. If not, write to the -- Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA -- 02111-1307, USA. -- -- As a special exception, if other files instantiate generics from this -- library, or you link this library with other files to produce an -- executable, this library does not by itself cause the resulting -- executable to be covered by the GNU General Public License. This -- exception does not however invalidate any other reasons why the -- executable file might be covered by the GNU General Public License. -- -- Portions of Onions have been derived from version 1.02 of the Garlic -- library of GLADE, the Ada95 Distributed Systems Annex for GNAT. GLADE -- is maintained by ACT Europe (see ). -- -- GLADE is Copyright (C) 1996,1997 Free Software Foundation, Inc. -- All source code that is shared by both GLADE version 1.02 and -- the Onions library remains under the FSF copyright. -- ----------------------------------------------------------------------------- Installation ------------ Onions is intended to be installed as one component of a larger system. As such, there should be a file called ../INSTALL which explains how to install the library on your system. In most cases, installation involves running the configure script. We have included the files for using automake and autoconf (GNU programs for building portable configure scripts) to automatically create the Makefiles, since that may be helpful for programmers distributing Onions along with their own code. Documentation ------------- There isn't any. Until we get something written up, you'll have to read the comments in the code and the example programs in ../Examples. More information can be found at the libwww-ada95 website: http://www.ics.uci.edu/pub/websoft/libwww-ada95/ Onions is organized around a cohesive set of modules: Onions The top-level package is mostly for naming purposes, but also contains some utility functions for rendering basic Ada95 types as a String (without that annoying leading space). Onions.Buckets Buckets is an ADT for raw octet (byte) data strings. The primary advantage of using Buckets instead of Strings or Storage_Arrays or Stream_Element_Arrays or C.char_arrays is that we can control their memory structure without worrying about the dope vector, avoid unnecessary copies, ensure that the memory is pool-based (and thus can be freed by routines that do not know its origin), and perform more efficient moves to other data structures. Buckets is probably incomplete -- we've just been adding utility routines as they are needed. Onions.Instreams Onions.Outstreams The heart of Onions is the input and output stream object classes and classwide types for building a data stream via a stack of stream objects (Input_Pipe and Output_Pipe). Reading from the head of an input pipe causes the head stream object to read from the next outbound stream object, and on down the line. Likewise for writing to the head of an output pipe. One of the main features of streams is that they can filter the data as it passes, converting, adding to, and/or removing from the data before giving it to the next object. Since multiple streams can be cascaded, the complete data conversion is the sum of the individual data conversions performed by the stream objects. Terminology: downstream -- the direction the data is supposed to be processed; upstream -- the direction opposite of downstream; inbound -- toward the client (i.e., from the network); outbound -- away from the client (i.e., to the network); The Onions Streams model is loosely based on the general design of UnixSV STREAMS, which is a method for building device drivers as a stack of modules. Henrik Frystyk Nielsen adopted this model in his redesign of the W3C Sample Code Library (libwww), also calling them streams, but in this case the stream objects reside in user-space rather than kernel-space. It is an excellent design for high-speed networking, since it maximizes flexibility in processing the data stream while at the same time minimizing the copying of data between memory structures. Our version uses Henrik's conceptual design, but transmogrified into Ada95 objects with classwide interfaces that dispatch to the object-specific procedures. Our streams are thread-blocking, but not process-blocking, which corresponds to an Ada95 model of per-thread readers instead of Henrik's C callbacks. Note that each stream head can only be written to or read from a single thread at a time -- the objects are not protected by default (too much overhead). It is often confusing to use the term Streams in Ada95, since there is already the predefined packages Ada.Streams (which is primarily intended for object serialization) and C_Streams (which is really just a binding to the Unix stdio library). Onions stream objects inherit from Ada.Streams.Root_Stream_Type so that they can also be used for Ada95 object transmission by other people who might need a network streams binding. We won't be using that interface for our own work, since Buckets are more efficient. Unlike Ada.Streams.Stream_IO, our streams act like STREAMS: you can read from the head of an Input_Pipe and write (append) to the head of an Output_Pipe. Stream objects are attached to each other like a stack, and stream filters can be pushed onto the stack and popped off the stack at any time. Whether or not a stream is buffered is determined privately within the stream object, so the amount of buffering done by a pipe will depend on how each object in the pipe is defined. Unprocessed data is pushed back upstream when a read-buffering stream object is popped, and flushed downstream when a write-buffering object is popped. Onions.Instreams.File Onions.Outstreams.File The File stream class is a stream end that performs buffered or unbuffered reads/writes on a filesystem descriptor. The Open function is used to open a file (or STDIN/OUT/ERROR) for the stream, returning a stream pipe. Think of it as Stream_IO without all the cruft. Onions.Instreams.Channel Onions.Outstreams.Channel The Channel stream class is used as the front-end for a socket connection (typically using TCP/IP) as established by the Connection Manager. It allows a stream to be closed, reset, or aborted without losing the connection, thus enabling things like HTTP's persistent connections. Onions.Instreams.Dir The Directory stream class is an input stream that reads each filename in a filesystem directory (excluding ".." and ".") and returns them one at a time (a filename in every bucket). See Onions.Instreams.HTML_Dir in the libwww-ada95/WWW area for an example of a filter that takes the directory stream and produces an HTML table containing information about the directory's contents. Onions.Instreams.Linebuf The Linebuf stream class is an input stream that waits until a complete line is available before it passes data on to a reader. It isn't very useful, but we'll use it to implement other stream objects (like a MIME header field parser) that is useful. Onions.Connections The Onions Connection Manager controls the number of active TCP socket connections used by a client application and keeps track of persistent connections (sockets that are currently connected to a host and waiting to be reused). A Connection object is defined with methods for establishing the connection and aborting/releasing each half of the connection, thus providing an interface between the Channels and the Connection Manager. Onions.Sockets The Sockets package provides utility routines for connecting via sockets, accepting connections via sockets, and setting socket options. Onions.Naming The Naming package provides utility routines for obtaining network addresses from an Internet hostname, etc. Onions.Constants The C system library uses many constants that are defined within the standard include files. This package is generated by constants.sh to provide us with Ada95 names for the same constants. Onions.Thin The Thin package provides a thin binding to the C system library of typical Unix/POSIX machines. It is not a strict POSIX interface because there is no such thing as a strict POSIX machine. Hopefully it is a subset of what is available on your machine. Onions.OS The OS package provides a slightly thicker binding to some operating system-dependent routines. The package spec is generated by configure, so portability problems should be fixed via hooks within this package and its C back-end: os-depend.h os-depend.c os-depend contains an operating system-independent interface to those C system library routines and data structures that are often system-dependent. Since Ada95 has no equivalent to the standard include files of C, we can't rely on a simple Import to match the C data structure with our Ada95 equivalent. We thus produce system-independent data structures here that can be matched (and imported) via Onions.OS. config.h The supplied configure program generates this include file to answer the OS-dependent portability questions. Onions.List_Queues The List_Queues generic package is used by Buckets to provide the Bucket_List and Bucket_Brigade types. The dual item/list interface allows optimal storage and manipulation of the data stream. Onions.Pointers The Pointers generic package allows us to do C pointer arithmetic on arbitrary storage element types. We may not need it. Top Ten reasons why it is called "Onions" ----------------------------------------- 10. The name "Onions" wasn't being used by any other software. 9. We need a reason? 8. It brought tears to our eyes when we discovered Ada95 didn't already have a network streams library. 7. Onions: Not In the OrigiNal Schedule. 6. The other thing that gives you bad breath. 5. One Network Interface ON Steroids. 4. Mmmmmm, food. 3. Our New Interface Of Network Streams. 2. It reminds me of Garlic. 1. A good network interface should be constructed using a layered paradigm in order to maximize portability and extensibility (changing of underlying layers without affecting the interface), but at the same time must avoid the performance cost of multiple data copies between buffers, uncached DNS lookups, poor connection management, etc. Onions are layered, but none of the layers are wasted in preparing a meal. Platforms --------- We have only tested Onions on our own development platform, Solaris 2.5. Onions has been reported to work on ... Onions was developed using the GNAT 3.10p compilation system. We have made every effort to keep the Ada95 source code independent of the compiler, but the Makefiles generated by configure may be GNAT-dependent. We have no idea how to port it to other compilers, but please let us know if you do and what changes (if any) are needed. Note that the library has been designed to maximize portability even though we didn't have the resources to test it on other platforms. Future Development ------------------ We have (long ago) exhausted all of our resources for further development of the libwww-ada95 and Onions libraries. We are currently looking for a new source of support for the library, either in the form of a long-term grant or by transition to another organization with a history of Ada95 and open-source software development. If you are interested, please contact us. Project status and updates can be found at http://www.ics.uci.edu/pub/websoft/libwww-ada95/ A mailing list has been established for discussion of development and future support for libwww-ada95 and Onions. To subscribe, send a message to with "subscribe" in the Subject. A hypermail archive of the mailing list is available at the website. Onions History -------------- Created in 1997 by Roy T. Fielding, Kari Nies, and Yuzo Kanomata. Principal Investigator: Dr. Richard N. Taylor The Onions library has been developed by the Hyperware research group in Information and Computer Science at the University of California, Irvine, in order to provide the network layer and basic streams types of a reasonably-high-performance protocol library for World Wide Web clients written in the Ada95 language. For more information about Hyperware and libwww-ada95, see . Garlic History -------------- Onions was started by extracting the system and socket interfaces from the Garlic library of GLADE 1.02 (an implementation of the Ada95 Distributed Systems Annex of Ada95), though almost everything has been changed since then. GLADE 1.02 was jointly developed by Ada Core Technologies and a research team from the Ecole Nat. Sup. de Telecommunication (Paris & Brittany). The ENST team comprises: Yvon Kermarrec, Laurent Nana, Laurent Pautet, and Samuel Tardieu. For more information on GLADE, see .