[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 (OO) toolkit that implements fundamental design patterns for communication software. ACE provides a rich set of reusable C++ wrappers, class categories, and frameworks that perform common communication software tasks across a range of operating system platforms. The communication software tasks provided by ACE include event demultiplexing and event handler dispatching, service initialization, interprocess communication, shared memory management, message routing, dynamic (re)configuration of distributed services, multi-threading, and concurrency control. ACE is targeted for developers of high-performance communication services and applications on UNIX, POSIX, and Win32 platforms. ACE simplifies the development of OO network applications and services that utilize interprocess communication, event demultiplexing, explicit dynamic linking, and concurrency. ACE automates system configuration and reconfiguration by dynamically linking services into applications at run-time and executing these services in one or more processes or threads. ACE has been ported to a wide range of uni-processor and multi-process OS platforms including Win32 (i.e., WinNT and Win95), most versions of UNIX (e.g., SunOS 4.x and 5.x, SGI IRIX, HP-UX, OSF/1, AIX, Linux, and SCO), VxWorks, and MVS OpenEdition. It is currently used in commercial products by dozens of companies including Ericsson, Bellcore, Siemens, Motorola, and Kodak. There are both C++ and Java versions of ACE available. The remainder of this document outlines the structure and participants of the layers in this diagram. C++ Wrappers for OS Interfaces The lower-level portions of ACE provide a set of portable and type-secure C++ wrappers that encapsulate the following C language OS interfaces: . IPC mechanisms -- e.g., Internet- and UNIX-domain sockets, TLI, Named Pipes (for UNIX and Win32) and STREAM pipes; . Event demultiplexing -- e.g., select(), poll(), and Win32 WaitForMultipleObjects and I/O completion ports; . Multi-threading and synchronization -- e.g., Solaris threads, POSIX Pthreads, and Win32 threads; . Explicit dynamic linking -- e.g., dlopen/dlsym on UNIX and LoadLibrary/GetProc on Win32; . Memory-mapped files and shared memory management -- e.g., BSD mmap(), SYSV shared memory, and Win32 shared memory; . System V IPC -- e.g., shared memory, semaphores, message queues. The OS Adaptation Layer shields the upper levels of ACE from platform dependencies associated with the underlying OS interfaces. Frameworks and Class Categories ACE also contains a higher-level network programming framework that integrates and enhances the lower-level C++ wrappers. This framework supports the dynamic configuration of concurrent distributed services into applications. The framework portion of ACE contains the following class categories: . The Reactor -- Supports both Reactive and Proactive I/O; . The Service Configurator -- Support dynamic (re)configuration of objects; . The ADAPTIVE Service Executive -- A user-level implementation of System V STREAMS, that supports modular integration of hierarchically-related communicaion services; . Concurrency -- Various types of higher-level concurrency control and synchronization patterns (such as Polymorphic Futures and Active Objects); . Shared Malloc -- Components for managing dynamically allocation of shared and local memory; . CORBA integration -- Integrates ACE with CORBA implementations (such as single-threaded and multi-threaded Orbix and Visibroker for C++). Distributed Services and Components Finally, ACE provides a standard library of distributed services that are packaged as components. These service components play two roles in ACE: 1. They provide reusable components for common distributed system tasks such as logging, naming, locking, and time synchronization. 2. They illustrate how to utilize ACE features such as the Reactor, Service Configurator, Service Initialization, Concurrency, and IPC components. ACE is currently being used in many commercial products including the Bellcore Q.port ATM signaling software product, the Ericsson EOS family of telecom switch monitoring applications, the Motorola Iridium global mobile communications system, and enterprise-wide electronic medical imaging systems for Kodak Health Imaging Systems and Siemens medical engineering. OBTAINING ACE The current ACE release is provided as a tar file that is around 1.8 Meg compressed using GNU gzip. ACE may be obtained electronically from http://www.cs.wustl.edu/~schmidt/ACE-obtain.html. 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. ACE DIRECTORY STRUCTURE The following subdirectories are included in C++_wrappers.tar.gz file: . ace -- the source code and binaries for C++ components (note that all of these are at the same "level" in order to work around Windows NT lack of symbolic links...) . ASX -- higher-level C++ network programming framework based on System V STREAMs . Collections -- stacks, sets, strings, etc. . Concurrency -- wrappers for Solaris, POSIX, and Win32 threads . Connection -- implementations of connection establishment patterns . CORBA -- C++ wrappers that make it easier to work with CORBA . Debugging -- C++ assert macro, dump methods, method call tracing, etc. . IPC_SAP -- C++ wrappers around UNIX communication mechanisms . Addr -- wrappers for various network addressing formats . DEV_SAP -- wrapper for UNIX device I/O . FIFO_SAP -- wrapper for FIFOS (named pipes) . FILE_SAP -- wrapper for UNIX FILE *s . IO_SAP -- wrapper for low-level serial-line I/O . SOCK_SAP -- wrapper for BSD sockets . SPIPE_SAP -- wrapper for SVR4 STREAM pipes and connld . TLI_SAP -- wrapper for SVR4 TLI . . UPIPE_SAP -- inter-thread communication mechanism . Log_Msg -- library API for local/remote logging . Memory . Mem_Map -- wrapper for BSD mmap() memory mapped files . Shared_Malloc -- shared memory malloc/free classes . Shared_Memory -- wrapper for SysV/BSD shared memory . Misc -- miscellaneous C++ wrappers for the GNU getopt utility, Obstacks, GoF-style patterns . Name_Service -- client-side classes for distributed name service . OS -- encapsulation of UNIX and Win32 OS APIs . Reactor -- a framework for OO event demultiplexing and event handler dispatching . Service_Configurator -- a framework for dynamically linking/unlinking services into/from applications at run-time . System V IPC . SV_Message_Queues -- wrapper for SysV message queues . SV_Semaphores -- wrapper for SysV semaphores . SV_Shared_Memory -- wrapper for SysV shared memory . Timers -- High resolution timers and profile timers . Token_Service -- client-side classes for distributed locking . apps -- Several example applications written using the ACE wrappers . Gateway -- application-level gateway . Orbix-Examples -- examples of how to integrate Orbix with ACE . gperf -- a perfect hash function generator program written in C++ . Synch-Benchmarks -- benchmarks for OS IPC and synchronization mechanisms . bin -- utility programs for building this release, in particular, a set of scripts for automatically generating manual pages from C++ class headers. . examples -- programs that illustrate how to use ACE components . man -- manual pages for ACE in nroff and HTML format generated automatically by OSE class2man . netsvcs -- network services . clients -- test programs that exercise the ACE network services . lib -- network services implemented using the general ACE service framework: . Client Logger -- client-side for distributed logging service . Server Logger -- server-side for distributed logging service . Name Server -- a distributed name service . Token Server -- a distributed token service . Time Server -- a distributed time service . servers -- dynamically linkable main programs that configure the services . 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. . tests -- a suite of automated regression tests to exercise ACE features ACE DOCUMENTATION AND TUTORIALS 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: . 4th IEEE International Conference on Software Reuse in Orlando, Florida, April 1996. . The SIGS OOP conference in Munich, Germany, February, 1996 . The OOPSLA '95 conference in Austin, TX, October 1995 . The ECOOP '95 conference in Aarhus, Denmark, June 1995 . The SIGS Object Expo conference in New York, NY, June, 1995 . The 1st USENIX Conference on Object-Oriented Technologies 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. A collection of white papers and tutorial handouts are included with the release. The documentation is stored in the ACE-documentation directory on wuarchive.wustl.edu (approximately 4 meg compressed). This directory contains postscript versions of various papers that describe different aspects of ACE. You might want to read SUG-94.ps first, since it gives an overview of the toolkit. Document Published in or presented at -------- ---------------------------- Acceptor-Connector.ps "Acceptor and Connector: Design Patterns for Actively and Passively Initializing Network Services." Presented at the EuroPLoP workshop held in conjunction with the ECOOP '95 conference, August 1995 ACE-concurrency.ps "An OO Encapsulation of Lightweight OS Concurrency Mechanisms in the ACE Toolkit." Washington University technical report WUCS-95-31. ACT.ps "Asynchronous Completion Token" submitted to the ``3rd Pattern Languages of Programs conference,'' Allerton Park, Illinois, September, 1996. Active-Objects.ps "Active Object: an Object Behavioral Pattern for Concurrent Programming," the proceedings of the Pattern Languages of Programs Conference, September 1995 Atomic_Op-94.ps "Transparently Parameterizing Synchronization into a Concurrent Distributed Application", C++ Report, July/August 1994 C++-report-col1.ps C++ Report Object Interconnections Column 1 C++-report-col2.ps C++ Report Object Interconnections Column 2 C++-report-col3.ps C++ Report Object Interconnections Column 3 C++-report-col4.ps C++ Report Object Interconnections Column 4 C++-report-col5.ps C++ Report Object Interconnections Column 5 C++-report-col6.ps C++ Report Object Interconnections Column 6 C++-report-col7.ps C++ Report Object Interconnections Column 7 C++-USENIX-94.ps "ASX: an Object-Oriented Framework for Developing Distributed Applications," 6th USENIX C++ Conference, April 1994 C++-world-93.ps "An Object-Oriented Framework for Developing Network Server Daemons", 2nd C++ World conference, Dallas, Texas, October 1993 C++-wrappers.ps "Systems Programming with C++ Wrappers: Encapsulating Interprocess Communication Services with Object-Oriented Interfaces", C++ Report, September/October 1992 CACM-95.ps "Experience Using Design Patterns to Develop Reuseable Object-Oriented Communication Software," Communications of the ACM, Special Issue on Object-Oriented Experiences, Vol. 38, No. 10, October, 1995. COOTS-95.ps "Object-Oriented Components for High-speed Network Programming," 1st USENIX Conference on Object-Oriented Technologies, April 1995. COOTS-96.ps "Design and Performance of an Object-Oriented Framework for Electronic Medical Imaging," 2nd USENIX Conference on Object-Oriented Technologies, June 1996. Connector.ps "A Design Pattern for Actively Initializing Network Services," C++ Report, January 1996 daemon-design-94.ps "A Domain Analysis of Network Daemon Design Dimensions", C++ Report, March/April 1994 DC-Locking.ps Double-Checked Locking, submitted to the ``3rd Pattern Languages of Programs conference,'' Allerton Park, Illinois, September, 1996. ECOOP-95.ps "Experiences Using Design Patterns to Evolve System Software Across Diverse OS Platforms," ECOOP '95 conference, August 1995 External-Polymorphism.ps "External Polymorphism: an Object Structural Pattern for Transparently Extending Concrete Data Types," submitted to the ``3rd Pattern Languages of Programs conference,'' Allerton Park, Illinois, September, 1996. EuroPLoP.ps Acceptor and Connector, Design Patterns for Initializing Communication Services, 1st European Conference on Pattern Languages of Programs, Kloster Irsee, July, 1996. IPC_SAP-92.ps "IPC_SAP: An Object-Oriented Interface to Interprocess Communication Services" C++ Report, November/December 1992 JPDC-96.ps "The Performance of Alternative Threading Architectures for Parallel Communication Subsystems", Submitted to the Journal of Parallel and Distributed Computing. PLoP-94.ps "Reactor: An Object Behavioral Pattern for Concurrent Event Demultiplexing and Event Handler Dispatching," Pattern Languages of Programs Conference, August 1994 PLoP-95.ps "Half-Sync/Half-Async: A Pattern for Efficient and Well-structured Concurrent I/O Systems." Pattern Languages of Programs Conference, September 1995 Reactor1-93.ps "The Reactor: An Object-Oriented Interface for Event-Driven UNIX I/O Multiplexing (Part 1 of 2)" C++ Report, February 1993 Reactor2-93.ps "The Object-Oriented Design and Implementation of the Reactor: A C++ Wrapper for UNIX I/O Multiplexing (Part 2 of 2)" C++ Report, September/October 1993 IWCDS.ps "The Service Configurator Framework: An Extensible Architecture for Dynamically Configuring Concurrent, Multi-Service Network Daemons", 2nd IEEE International Workshop on Configurable Distributed Systems, March 1994 Service-Configurator.ps "Service Configurator," submitted to the ``3rd Pattern Languages of Programs conference,'' Allerton Park, Illinois, September, 1996. SIGCOMM-95.ps "AITPM: a Strategy for Integrating IP with ATM," SIGCOMM '95, August, 1995. SIGCOMM-96.ps "Measuring the Performance of Communication Middleware on High-Speed Networks," SIGCOMM '96, August, 1996. SUG-94.ps "The ADAPTIVE Communication Environment: An Object-Oriented Network Programming Toolkit for Developing Communication Software", 11th and 12th Sun Users Group Conference, December 1993 and June 1994 TAPOS-95.ps "A System of Reusable Design Patterns for Communication Software," The Journal of Theory and Practice of Object Systems Special Issue on Patterns and Pattern Languages TSS-pattern.ps "Thread-Specific Storage: A Pattern for Reducing Locking Overhead in Concurrent Programs," submitted to the ``3rd Pattern Languages of Programs conference,'' Allerton Park, Illinois, September, 1996. I update these papers periodically to reflect changes to the ACE architecture. Therefore, you might want to check the date on the files to make sure that you have read the most recent versions of these papers. ACE TUTORIALS I update these papers periodically to reflect changes to the ACE architecture. Therefore, you might want to check the date on the files to make sure that you have read the most recent versions of these papers. There may not be enough space on this ftp server to store the following tutorial handouts: OOCP-tutorial4.ps SIGS Object Expo, June 1995. SIGS OOP '95 conference, February, 1995; USENIX Winter Conference, January 1995; OONP-tutorial4.ps ECOOP conference, August 1995 USENIX Conference on Object-Oriented Technologies, June 1995; 3rd SIGS C++ World conference, November, 1994; 9th ACM OOPSLA conference, October 1994; 6th USENIX C++ Conference, April 1994; 2nd SIGS C++ World conference, October 1993; CORBA4.ps "Measuring the Performance of Object-Oriented Components for High-speed Network Programming," Object Expo, June 1995; USENIX Conference on Object-Oriented Technologies, June 1995 HP Labs, June 1995 corba4.ps "An Overview of CORBA" Washington University Distributed Operating Systems class These handouts are available via WWW at URL: http://www.cs.wustl.edu/~schmidt/ as at wuarchive.wustl.edu in the directory /languages/c++/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 (on both SPARC and Intel platforms) using Sun C++ 4.x and GNU G++ 2.7.x. The release has also been ported to SCO UNIX, HP-UX, SGI, OSF/1, AIX, Linux, Windows NT and Windows '95. I expect that major portions of the release will port easily to other platforms. If you can help port ACE to other platforms I'd appreciate it. 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@cs.wustl.edu if you'd like to join the mailing list. COPYRIGHT INFORMATION FOR ACE ACE is copyrighted Douglas C. Schmidt and his research group at Washington University. You are free to do anything you like with the ACE source code such as including it in commercial software, as long as you include this copyright statement along with code built using ACE. 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). Please note, however, that you may not do anything to the ACE code that will prevent it from being distributed freely (such as copyrighting it). Naturally, neither I nor my research group is responsible for any problems caused by using ACE. My goal is to see ACE continue to evolve and become a more comprehensive, robust, and well-documented C++ class library that is freely available to researchers and developers. If you have any improvements, suggestions, and or comments, I'd like to hear about it. Thanks, Douglas C. Schmidt schmidt@cs.wustl.edu ACKNOWLEDGEMENTS ACE has been deeply influenced and improved by the following members of my research group at Washington University: Aniruddha Gokhale Tim Harrison James Hu Prashant Jain Irfan Pyarali David Levine I would also like to thank all the following people who have also contributed to ACE over the years: Paul Stephenson Olaf Kruger Ed Brown Lee Baker Alex Ranous Mark Patton Steffen Winther Sorensen for Chris Cleeland Tim Harrison Troy Warner Stacy Mahlon Charles Eads Mark Frutig Todd Hoff George Aniruddha Gokhale Irfan Pyarali Prashant Jain Brad Needham Leslee Xu Detlef Becker Bruce Worden Chris Tarr Bill Sears Greg Lavendar Steve Warwick Mats Sundvall Andreas Ueltschi Nigel Hooke Medhi Tabatabai Stuart Powell Bin Mu Andrew McGowan Ken Konecki John P. Hearn Giang Hoang Nguyen Carlos Garcia Braschi Jam Hamidi Eric Vaughan Karl-Heinz Dorn Steve Ritter Chandra Venkatapathy Matt Stevens Bob Vistica David Trumble John Morey George Reynolds Hans Rohnert Alex V. Maclinovsky Todd Blanchard Rob Clairmont Christian Millour Neil Cohen Dieter Quehl Reginald S. Perry James Morris Mark Seaborn Phil Brooks E. Jason Scheck Daniel Proulx Bill Tang John Huchinson Jack Erickson Byron Walton Bill Lear Mark Zusman Aurelio Nocerino Walt Akers Greg Baker Alexandre Karev Pramod Kumar Singh Bryon Rigg Brad Brown Patty Genualdi Eshel Liran Mick Adams Chris Eich Mike Flinn Audun Tornquist Sandeep Joshi Kirk Sinnard <1764@mn.lawson.lawson.com> Bernd Hofner Craig Perras Kirk Sinnard Matthew Newhook Gerolf Wendland Phil Mesnier Ross Dargahi Richard Orr Rich Ryan Jan Rychter Tom Marrs <0002104588@mcimail.com> Bob Olson Jean-Francois Ripouteau Ajit Sagar Ashish Singhai David Sames Gonzalo Diethelm Raj Darrin Steve Weismuller Eric C. Newton Andres Kruse Ramesh Nagabushnam Antonio Tortorici Nigel Lowe Tom Leith Greg Wilson Michael Fortinsky Marco Sommerau Gary Salsbery Eric Beser Alfred Keller John Lu James Mansion Jesper S. M|ller Chris Lahey Michael R"uger Istvan Buki Greg Wilson Jack Erickson Garrett Conaty Brad Flood Marius Kjeldahl Steve Huston Eugene K. Plaude Joseph DeAngelis Kim Gillies Luca Priorelli Alan Stewart Hani Yakan William L. Gerecke Craig Johnston Pierre-Yves Duval Rochi Febo Dommarco Jonathan Biggar Scott Shupe Chuck Gehr Avraham Nash Padhu Ramalingam Jay Denkberg Ayman Farahat Tilo Christ Ari Erev Hamutal Yanay Vital Aza Alex Villazon David Artus Todd Barkalow Alexander Smundak Thilo Kielmann Matthias Kerkhoff Fred LaBar Hanan Herzog Eric Parker James Michael Dwyer Arun Katkere Bob Dunmire Sandro Doro Robert Lyng Phil Logan John Cosby Wayne Vucenic I would particularly like to thank Paul Stephenson, who worked with me at Ericsson and is now at ObjectSpace. Paul devised the recursive Makefile scheme that underlies this distribution and also spent countless hours with me discussing object-oriented techniques for developing distributed application frameworks. Finally, I'd also like to thank Todd L. Montgomery , fellow heavy metal head, for fulfilling his quest to get ACE to compile with GCC!