[An HTML version of this README file is available at the following URL

http://www.cs.wustl.edu/~schmidt/ACE.html.  

All software and documentation is available via both anonymous ftp and
the World Wide Web.]

THE ADAPTIVE COMMUNICATION ENVIRONMENT (ACE)

An Object-Oriented Network Programming Toolkit

OVERVIEW OF ACE

The ADAPTIVE Communication Environment (ACE) is an object-oriented
network programming toolkit.  ACE encapsulates the following
user-level BSD UNIX and System V Release 4 (SVR4) UNIX IPC facilities
via type-secure, object-oriented interfaces:

        . UNIX IPC mechanisms 
                -- Internet- and UNIX-domain sockets, TLI, Named pipes
                (FIFOs) and STREAM pipes (note that a Windows NT
                version of Internet-domain sockets is also available).
        . Event multiplexing
                -- select() and poll()
        . Multi-threading
                -- Solaris and DCE pthreads             
        . SVR4 explicit dynamic linking facilities 
                -- dlopen/dlsym/dlclose
        . The mmap family of memory-mapping APIs
        . System V IPC 
                -- shared memory, semaphores, message queues
        . Sun RPC 
                -- GNU rpc++, written by Michael Lipp

In addition, ACE contains a higher-level network programming framework
that integrates and enhances the lower-level C++ wrappers.  This
framework supports the dynamic configuration of concurrent network
daemons composed of application services.  This framework contains 
the following class categories:

        . The Reactor 
        . The Service Configurator
        . The ADAPTIVE Service Executive

Many of the C++ wrappers and higher-level components have been
described in issues of the C++ Report, as well as in proceedings of
the following journals, conferences, and workshops:

        . The ECOOP '95 conference in Aarhus, 1995
        . The SIGS Object Expo conference in New York, NY, June, 1995
        . The 1st USENIX COOTS conference in Monterey, CA, June, 1995
        . The SIGS OOP conference in Munich, Germany, February, 1995
        . The Winter USENIX General Conference in January, 1995
        . 3rd SIGS C++ World conference in November, 1994
        . The 9th ACM OOPSLA Conference held in October, 1994 
        . The 1st Conference on the Pattern Languages of Programs, 
                August, 1994
        . The 6th USENIX C++ Conference, April, 1994
        . The 2nd IEEE International Workshop on Configurable Distributed
                Systems, March, 1994
        . The 11th and 12th Annual Sun Users Group Conference in
                December, 1993 and June, 1994 
        . The 2nd SIGS C++ World conference, October, 1993
        . IEE Distributed Systems Engineering Journal, December 1994.

ACE is currently being used in a number of commercial products
including the Bellcore Q.port ATM signaling software product, the
Ericsson EOS family of PBX monitoring applications, the Motorola
Iridium global mobile communications system, and the Global Limiting
System for Credit Suisse.

OBTAINING ACE

ACE is available for anonymous ftp from the ics.uci.edu (128.195.1.1)
host in the gnu/C++_wrappers.tar.Z file (approximately 1 meg
compressed).  This release contains contains the source code, test
drivers, and example applications for C++ wrapper libraries and the
higher-level ACE network programming framework developed as part of
the ADAPTIVE project at the University of California, Irvine and at
Washington University.

The following subdirectories are included in C++_wrappers.tar.Z file:

        . apps    -- Several example applications written using the ACE wrappers
        . bin     -- utility programs for building this release
        . build   -- a separate subdirectory that keeps links into the main
                     source tree in order to facilitate multi-platform
                     build-schemes
        . include -- symbolic links to the include files for the
                        release 
        . lib     -- object archive libraries for each C++ wrapper
                        library 
        . libsrc  -- the source code for the following C++ wrappers:

                . ASX -- higher-level C++ network programming
                        framework based on System V STREAMs
                . Connection -- implementations of connection
                        establishment patterns 
                . Get_Opt -- a C++ version of the UNIX getopt utility
                . SOCK_SAP -- wrapper for BSD sockets
                . TLI_SAP -- wrapper for SVR4 TLI 
                . FIFO_SAP -- wrapper for FIFOS (named pipes)
                . SPIPE_SAP -- wrapper for SVR4 STREAM pipes and connld 
                . Log_Msg -- library API for a local/remote logging
                        facility 
                . Mem_Map -- wrapper for BSD mmap() memory mapped files 
                . Message_Queues -- wrapper for SysV message queues
                . Reactor -- a framework for event demultiplexing and
                        event handler dispatching 
                . Semaphores -- wrapper for SysV semaphores
                . Service_Configurator -- a framework for dynamically
                        linking/unlinking services into/from applications
                        at run-time
                . Shared_Memory -- wrapper for SysV shared memory
                . Shared_Malloc -- wrapper for SysV/BSD shared mallocs
                . Threads -- wrappers for Solaris 2.x threads
        
        . man   -- manual pages for ACE in nroff and HTML format
                   generated automatically by OSE class2man
        . rpc++ -- C++ interface to Sun RPC developed by Michael Lipp
                   (mnl@dtro.e-technik.th-darmstadt.de).  This code
                   is distributed "as is" (under the GNU GPL) and is 
                   not part of the ACE release that I maintain.
        . src   -- symbolic links to all the source code.  This makes
                   it easy to build a single *.a and *.so file...
        . tests -- programs that illustrate how to use the various
                        wrappers 
        . WIN32 -- contains the versions of ACE that are ported to 
                   Windows NT (currently on the SOCK_SAP C++ wrappers
                   for sockets are ported)

In addition, a collection of white papers and tutorial handouts are
included with the release.  The documentation is stored in
gnu/C++_wrappers_doc.tar.Z file (approximately 2.5 meg compressed).
The following directory is included along with the documentation:

        . papers  -- postscript versions of various papers describing ACE 

BUILDING AND INSTALLING ACE

Please refer to the INSTALL file for information on how to build and
test the ACE wrappers.  The overall ACE release is very large (~1
Meg).  Therefore, I'm sorry, but I will be unable to distribute the
ACE wrappers via email.  The BIBLIOGRAPHY file contains information on
where to obtain articles that describe the ACE wrappers and the
ADAPTIVE system in more detail.

The current release has been tested extensively on Sun workstations
running Sun OS 4.1.x and Solaris 2.x using Sun C++ 3.x and 4.x (GNU
G++ may work, but has not been tested extensively).  Portions of the
release have also been ported to SCO UNIX, HP-UX, SGI, OSF/1, AIX,
Linux, Windows 3.1, and Windows NT.  I expect that major portions of
the release will port easily to other platforms.  If anyone is willing
to help coordinate ports to other platforms please let me know.

ACE MAILING LIST

A mailing list is available for discussing bug fixes, enhancements,
and porting issues regarding ACE.  Please send mail to me at the
ace-users-request@ics.uci.edu if you'd like to join the mailing list.

COPYRIGHT INFORMATION FOR ACE

You are free to do anything you like with the ACE source code such as
including it in commercial software.  Moreover, you are under no
obligation to freely redistribute any of your source code that is
built using ACE (be aware that rpc++ is distributed under the GNU GPL,
which has a different copyright policy).  However, you may not do
anything to the original ACE code contained in this release that will
prevent it from being distributed freely (such as copyrighting it,
etc.).  If you have any improvements, suggestions, and or comments,
I'd like to hear about it!  It would be great to see this distributed
evolve into a comprehensive, robust, and well-documented C++ class
library that would be freely available to everyone.  Naturally, I am
not responsible for any problems caused by using these C++ wrappers.

        Thanks,
        
        Douglas C. Schmidt 
        schmidt@cs.wustl.edu 

ACKNOWLEDGEMENTS
        
Special thanks to Paul Stephenson (paul.stephenson@ebu.ericsson.se)
for devising the recursive Makefile scheme that underlies this
distribution, as well as for devoting countless hours to discussing
object-oriented techniques for developing distributed application
frameworks.

Thanks to Olaf Kruger for explaining how to instantiate templates for
shared libraries on SunOS 4.
 
The following people have also contributed to ACE:

Ed Brown (eebrown@netcom.com)
Lee Baker (baker@ctis.af.mil)
Alex Ranous (ranous@nsa.hp.com)
Mark Patton (mark_patton@tx72.mot.com)
Steffen Winther Sorensen <sts@dad.stibo.dk> for
Chris Cleeland (chris@milo.st-louis.mo.us)
Tim Harrison (harrison@cs.wustl.edu)
Troy Warner (tnw1@core01.osi.com)
Stacy Mahlon (mcs@contour.mayo.edu)
Charles Eads (eads@synoptics.com)
Mark Frutig (mfrutig@fnbc.com)
Todd Hoff (thm@ictv.com)
george@truffula.fp.trw.com
Aniruddha Gokhale (gokhale@cs.wustl.edu)
Irfan Pyarali (ip1@cs.wustl.edu)
Brad Needham (bneedham@arinc.com) 
Leslee Xu (lxu@ics.uci.edu)
