ACE Version 5.4 Release Notes
February 25, 2004
This document describes the additions, changes, and
fixes which were made to ADAPTIVE Communication Environment (ACE)
for version 5.4.
ACE is Open Source software, and the source kit is freely available from
the following locations:
Prebuilt, natively installable kits are available for a number of popular
platforms at the Riverace Kit Store. See the
ACE is discussed in the following forums:
Emmanuel Thevenot Beaufort
contributed a new macro,
ACE_TEXT_ALWAYS_WCHAR(STRING). It's the inverse of
ACE_TEXT_ALWAYS_CHAR(STRING) -- whatever STRING is,
the macro produces a wide-char string.
ACE was ported to the following platforms:
- Cygwin on Windows. This effort had many contributors, and was led
by Johnny Willemsen.
- Mac OS X. This effort was led by
John Michael Zorko. 10.2 and
10.3 work as well as the current OS capabilities and tool chain allow.
- Microsoft Windows using Visual C++ .NET 2003 (aka MSVC 7.1). The
Microsoft Visual C++ .NET 2002 compiler (aka MSVC 7.0) has many bugs
that the newer compiler resolves. Use of the 2003 (7.1) version is
strongly encouraged. Microsoft Visual C++ 6 is still supported.
has graciously contributed
a new development tool named MakeProjectCreator (MPC) -- The Makefile,
Project and Workspace Creator.
This tool can be used to generate tool specific input (e.g.,
Makefile, dsp, vcproj, etc). The generator takes platform and building
tool generic files (mpc files) as input which describe basic information
needed to generate a "project" file for various build tools. These tools
include GNU Make, NMake, Visual C++ 6, Visual C++ 7, etc.
One of the many unique and useful features of the Makefile, Project and
Workspace Creator is that the project definition files can employ the idea
of inheritance. This feature allows a user to set up a basic base project
(mpb file) that can contain information that is applicable to all
sub-projects. Things such as include paths, library paths and inter-project
dependencies could be described in this base project and any project that
inherits from it would contain this information as well.
Another set of files, known as template input files (mpd files), provides
the generator with the necessary information to fill platform and build
tool specific information for dynamic and static library and binary
Together, the generic input files and the template input files are applied
toward a platform and build specific template (mpt file) to create the final
product (a build tool specific input file). These templates contain
"variables" that are filled in by the project creator with information
gathered through the mpc and mpd files and possibly by default values set
within the template itself.
Most of ACE+TAO are now using MPC to generate the various Makefiles,
projects, and workspaces.
For complete MPC usage information, please see the README and USAGE files in
ACE_wrappers/bin/MakeProjectCreator. There is a chapter fully describing
MPC and its usage in OCI's TAO Developer's Guide. OCI has generously made
the MPC chapter from the guide available for download at
ACE_Codeset_Registry is a new facility that was added to support
TAO's Codeset translation framework. It is a wrapper for DCE code and
character set registry functions for platforms that support them, and
emulated where those functions are not available.
Support was added to ACE for using the Stream Control Transmission Protocol
(SCTP). SCTP is a new transport layer protocol
developed by the IETF and defined by RFC2960. Originally designed for the
transmission of message-oriented applications such as the transportation of
signaling data for PSTNs (Public Switched Telephone Networks), SCTP can be used
in any application that uses TCP.
The ACE_SOCK_SEQPACK_* classes implement this support. Please see
the reference documentation for those, as well as the README files
Lockheed Martin Advanced Technology Laboratories (LM ATL) development
of the SCIOP pluggable protocol for TAO was funded under DARPA/IXO's
Program Composition for Embedded Systems (PCES) program.
The LM ATL PCES project leads, Patrick Lardieri and Gautam Thaker,
thank the following individuals for their contributions to the
development TAO's SCIOP pluggable protocol.
- Jason Cohen, LM ATL
- Edward Mulholland, LM ATL
- Keith O'Hara, LM ATL
- Chuck Winters, LM ATL
We also thank Mr. Brian Bidulock of OpenSS7 (www.openss7.org) for his
rapid development of a fully functional Linux implementation of SCTP
which made this work possible.
We also thank the following individuals for their valuable review and
critiques of our SCIOP designs and for the expert advice on the more
arcane and subtle aspects of ACE and TAO.
- Dr. Chris Gill, DOC Group
- Balachandran Natarajan, DOC Group
Added a default value for optstring in the ACE_Get_Opt
constructor so that apps can more easily only use the long option format
without also having to provide a blank optstring.
Added a new method, ACE_Get_Opt::last_option(), which returns
the last option processed. This allows applications to see the actual command
line text of the last option that was found (or not found in
the case of an error). This is especially useful in cases where
the option was invalid and the caller wants to print out the
invalid value. Resolves bug 1338.
Added the ability for ACE_Configuration to have a default, or
unnamed, key. This is done with the help of a new
which deals with the differences between Windows and everything
else. Resolves bug 1374.
ACE_Configuration_Import_Export::import_config() was also
changed to allow unnamed keys.
ACE can now be configured and built using the standard GNU Auto Tools
capability. This method is not always as reliable as the traditional
configuration method, so be sure to test carefully when using it.
A description of how to use this facility is included in the
IPv6 support, first added in ACE 5.3, was completed. The main addition is
support for UDP multicast over IPv6 for Linux. Thanks to
for contributing this.
Added operator== and operator!= methods to ACE_Vector that
take the correct vector length into account. The inherited
ACE_Array methods run the whole array max length.
A new class, ACE_Vector_Iterator was added that iterates
over an ACE_Vector. It correctly detects end of the vector
content. ACE_Vector now uses this class to define its
Iterator trait. It previously used ACE_Array_Iterator
as the iterator, but it doesn't notice the end of the legit vector
The source code examples from The ACE Programmer's Guide are now
available in ACE_wrappers/examples/APG.
A large number of problems were fixed for version 5.4.
The more visible ones are described in this section. A complete
list of changes and fixes is available in the ChangeLog file in
the ACE source kit. For updated lists of bug reports and fixes, please
ACE Bugzilla page.
The ACE_NT_Service::wait_for_service_state() method was enhanced
to use the passed wait_time parameter. Thanks to
contributing this fix.
fix to release dynamically allocated memory in
ACE_Process_Manager::spawn() if the spawn operation fails.
Previously, when the XML parser converted an escape sequence, the length
reported to the characters() callback did not count the number
of characters preceding the substituted escape sequence. This has been
fixed. Thanks to Emmanuel Thevenot Beaufort
for this fix.
submitted a fix for the ACE_Vector::resize() method. Previously,
the last item in the vector was lost during the resize.
When ACE_Stream_Tail::put() releases the passed
ACE_Message_Block it returns 0, not -1. This is consistent with
the put() semantics elsewhere in ACE. Thanks to
for help with this.
The ACE 5.3 builds on IBM AIX with Visual Age C++ did not add the -g
option when a debug build was performed. This has been fixed.
fixed ACE_SPIPE_Stream::send_handle() and recv_handle()
to work correctly on Windows. This extension was necessary because the
receiving side must open the duplicate handle before the sending side
ACE_SSL_SOCK_Connector::ssl_connect() was fixed to properly
countdown the specified timeout when multiple iterations of
system calls are needed to complete the operation.
ACE_Select_Reactor-based reactors had a subtle problem corrected
that arose during complete shutdown of an event handler.
If an event handler's handle_close() hook registered a new
handle, it was possible that it would not be recognized. This has
A number of wide-character related fixes were made that make wide-character
applications much easier on Windows and Linux.
Fixed an occasional assertion failure during shutdown in
ACE_Thread_Manager. This was caused by
double deletion of an item in the ACE_Thread_Manager
terminated thread list in ACE_Thread_Manager::wait().
Thanks to Bruce McIntosh <email@example.com> for
suggesting the fix. [Bug 1505]
very large effort to reorganize ACE's OS abstraction layer.
A ace/os_include directory is new, and it contains a mirror of
the Single Unix specification's standard header files. These files now
include a platform's
applicable header files based on its configuration and account for
A number of miscellaneous macros are now in ace/Global_Macros.h
and ace/Default_Constants.h rather than ace/OS.h.
The OS.h header file should no longer be used. The ACE_OS methods
that previously were contained in it were all moved out to new
files, based on the Single Unix Specification's definition of where
they are defined. The new header files place the ACE_OS methods in
a ACE_OS namespace, not static methods of an ACE_OS class. The new
header files which should be uised instead of OS.h are:
Many changes were made to ACE's header files to decrease the number of
dependencies between them. This speeds up compilation times greatly.
A side-affect of these changes is that header files that were indirectly
included in previous ACE versions may no longer be included, and they'll have
to be included explicitly in your code when needed. Many programs will,
for example, need to add an include for "ace/Log_Msg.h".
The following changes are related to improving memory management
of Event Handlers when they interact with Reactors (and Timer
Queues). When a handler is registered with the Reactor, the
Reactor increments the reference count on the handler. The
Reactor also increments this reference count when making upcalls
on the handler. The reference count is decremented when an
upcall completes or when the handler is removed from the
This mechanism is particularly need for multi-threaded applications
that can have multiple threads executing upcalls on a handler
that needs to be shutdown in a safe manner. The following
illustrates an example of how this mechanism works:
This mechanism ensures that the handler is not deleted until the
final upcall thread exits the handler.
- When a handler is created, its reference count is one.
- After the handler is registered with the Reactor, its reference
count becomes two.
- At this point, the handler creator can let go of the handler
reference, bringing down the reference count to one.
- For each thread executing upcalls on the handler, the Reactor
increments the reference count by one. So if three threads were
simultaneously making upcalls on a handler, the reference count
would be four.
- Assuming an external event (and thread) decides to close the
handler. It simply removes the handler from the Reactor. This
decreases the reference count to three.
- As each thread completes their upcall, the reference reduces.
- Once the final thread exits the upcall, the reference reaches
zero, and the handler is finally deleted.
Reactors will now call new ACE_Event_Handler methods
remove_reference() during registrations, removals, and upcalls.
Reference counting is configurable and can be controlled by the
Reference_Counting_Policy which is disabled by default.
To enable reference counting on a handler, reset its
reference counting policy to "ENABLED".
To facilitate reference counting of handlers, an
ACE_Event_Handler_var class was added. This class is akin to
the CORBA PortableServer::ServantBase_var class.
It calls ACE_Event_Handler::remove_reference() in its destructor.
Similar reference counting related changes were made to the
Timer Queues so that handlers can be used in a thread safe
manner with the queues.
The ACE_Connector implementation was completely revised to utilize
the new memory management mechanisms and remove existing
concurrency bugs. ACE_Connector no longer needs to inherit from
ACE_Service_Object since it does not register with the Reactor.
We now use ACE_NonBlocking_Connect_Handler for handling
non-blocking connects. The resume(), suspend(), and
init() no-ops, and fini() and info() were removed.
Several new examples/tests were added to illustrate these additions
The reference-counting changes to the timer queue facility resulted in
some additions to the interface required by classes implementing the
FUNCTOR interface for ACE_Timer_Queue:
- registration(). This method is called when a timer is
- preinvoke(). This method is called when the timer expires,
just before making the upcall.
- upcall(). Changed the signature to pass
ACE_Timer_Node_Dispatch_Info_T instead of the individual
- postinvoke(). This method is called upon return from
- cancel_type() and cancel_timer(). Split
cancellation() into these
two methods. cancel_timer() is called when a timer is
canceled. cancel_type() is called when a handler is
canceled. Also added a dont_call parameter to these methods.
cancel_timer() will be used for reference counting and
cancel_type() will be used for calling handle_close().
The classes previously defined in ace/Synch.h and
ace/Synch_T.h have all been moved into new files, roughly
one per class, with the file name being the class name without the
leading ``ACE''. Application code should be changed to include just the files
needed, although including the Synch* files should still work
correctly for this ACE version.
The ACE_Bound_Ptr::get() method is now declared
The ACE_Refcounted_Auto_Ptr::get() method (and the associated
ACE_Refcounted_Auto_Ptr_Rep::get() method) are now declared
The ACE_Notification_Strategy::mask() method is now declared
ACE's shared memory allocators were corrected to do alignment properly on
64-bit platforms. This fix changed the default alignment from a
4-byte boundary to an 8-byte boundary. This is overridable; see comments
The ACE_New_Allocator::malloc(), calloc(), and
free() methods were uninlined to avoid multiple heap problems on
Windows. This was necessary to fix Bugzilla #1464.
ACE_TP_Reactor no longer allows users to register signal
handlers. ACE_TP_Reactor does not handle signals at
present and allowing this is simply confusing. It now returns a
value of -1 when requested to register a signal handler.
for pointing this out this inconsistency.
The 3rd argument to ACE_Log_Record::print() was changed from
ostream to ACE_OSTREAM_TYPE.
An advanced new timeprobe class was added. New features are a
ring buffer for elements kept in data structure.
This eliminates the ACE_ASSERT when an element
is attempted to be inserted into a full data
structure. Old data is overwritten until the
cache is read and cleared.
Timeprobes now include a second argument to
allow for an ACE_ALLOCATOR. This allocator allows
for the data structure that will contain the
ACE_Timeprobes to be done in the constructor. A
new function called 'increase_size' allows for
the data structure to increase the number of
measurements it can take. It does so by creating a
new structure with the new size and copying the
elements from the old structure.
Added a new Metrics Cache. No further information on this was provided
by the author. Please see ace/Metrics_Cache* for details.
The ACE GNU Make-based build scheme builds versioned shared libraries
when enabled. The SOVERSION make variable sets the version string. This
is now user-settable if versioned_so is enabled. Thanks to
Craig L. Ching
for this idea.
Users can set this stuff
up in their platform_macros.GNU file. The ACE_MAJOR_VERSION,
etc. variables are set up before platform_macros.GNU, though,
in case platform_macros.GNU wants to use them.
The ACE_Process copy constructor and
assignment operator methods were moved to the private part of the
class to disallow copying.
Two new files were added to simplify the makefile systems.
include/makeinclude/all_in_one.GNU replaces and conditionally
includes all the other standard makeinclude files. It also includes the new
component_check.GNU file that handles all the conditional
compilation rules. All you need to do is add a list of required
components needed for the particular project, e.g., rmcast,
shared_libs, Other, etc..., to REQUIRED_COMPONENTS and then
include all_in_one.GNU. These files will simplify MPC a great
The amount of information logged when a timestamp is request on
an ACE logging message can now be changed to be either the time or the
time and date. Defining the environment variable ACE_LOG_TIMESTAMP to be
either TIME or DATE. This fixes bug #1635.
Previous ACE versions favored use of TLI over XTI when both were available.
This has been reversed; XTI is now favored.
The current set of known ACE problems and enhancement requests can always be
found at the
ACE Bugzilla page.
Some more frequently encountered ones are listed here.
The ACE 5.4 kit from Washington University contains a directory named
aux which causes an error while unpacking on Windows. The
5.4 source kit from the Riverace Kit Store has this problem corrected.
ACE 5.4 does not compile successfully for Windows CE with either eMbedded
Visual C++ 3 or 4. This issue is being investigated and should be
resolved before ACE 5.4.1 and Riverace 5.4a.
ACE 5.4 does not compile successfully on HP-UX with g++. There is an
error in selecting the wrong select() signature. This will be
resolved by ACE 5.4.1 and Riverace 5.4a.
Some part sof the ACE 5.4 distribution get erratic link-time errors related
to missing templates on AIX using Visual Age C++ 6. This is a side-affect
of parallel build actions; any failed sections will build successfully if
built by itself.
If the ace/config.h file defines the Visual C++ macro VC_EXTRALEAN
before including ace/config-win32.h, compilation of ACE_NT_Service
will fail with an undefined type SERVICE_STATUS_HANDLE. To work around
this, do not set VC_EXTRALEAN.
The ACE_IOStream class template has not been updated to work
with standard iostreams implementations. It only works with ``old''
The tests/Proactor_Test program times out on some platforms, including
Solaris. These issues are being actively investigated. Decisions to use
asynchronous I/O and the Proactor framework should be carefully made;
the asynchronous I/O facilities on some plaforms are not stable
enough to base production systems on.
Asynchronous I/O remains a preferred and highly reliable method for
I/O on Windows.
The new Pthreads implementation in newer Red Hat Linux versions (9 and
Enterprise Linux 3) silently ignores requests to create threads with
non-default scheduling classes and priorities. This causes the
ACE Priority_Task_Test to report failures. Responsibility for fixing this
lies with the Linux kernel and/or glibc developers.
ACE Version 5.4 Release Notes
This document was generated using the
LaTeX2HTML translator Version 2K.1beta (1.47)
Copyright © 1993, 1994, 1995, 1996,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 ace54.tex
The translation was initiated by Steve Huston on 2004-02-25