ACE Version 5.2 Release Notes
December 5, 2001
This document describes the additions, changes, and
fixes which were made to ADAPTIVE Communication Environment (ACE)
for version 5.2.
ACE is Open Source software, and the source kit is freely available from
the following locations:
Pre-built, natively installable kits are available for a number of popular
platforms at the Riverace Kit Store,
ACE is discussed in the following forums:
idea and implementation for a new features which allows an
ACE_Event_Handler object's pending Reactor notifications to
be cancelled. To cancel notifications, call:
ACE_Reactor::purge_pending_notifications (ACE_Event_Handler *).
The ACE_Event_Handler class was also extended to automatically
call this function as part of its destructor if it has a ACE_Reactor
Note that this functionality does not have any affect on the
ACE_Select_Reactor (or any class derived from it, such as
ACE_TP_Reactor) unless the config option
ACE_HAS_REACTOR_NOTIFICATION_QUEUE is enabled. This
restriction does not apply to ACE_WFMO_Reactor or any class
derived from it.
ACE has been enhanced to work properly with the Visual Age C++ version 5
compiler, in both batch (command line) and incremental (IDE) mode.
Riverace supports ACE 5.2 on AIX 4.3.3 and higher, as well as AIX 5L
version 5.1 with Visual Age C++ 5. Riverace also support ACE 5.2 on
AIX 4.3.3 with the IBM C/C++ 3.6.6 compiler.
To unify the configuration procedure for these platforms, there is
a common platform_macros.GNU file named platform_aix_ibm.GNU
which replaces all previous files used for AIX 4.3 and higher with all
Support for gcc on AIX has been withdrawn by Riverace due to excessive
compiler problems. Support for gcc version 3.0.1 (or higher) on AIX may
be added at a later time.
ACE has been enhanced to allow building it with gcc 3.0.1. gcc 3.0 exhibited
some problems compiling ACE+TAO with optimizations enabled. gcc 3.0.1 fixes
ACE has been ported to Redhat Linux 7 and 7.1. Riverace now supports
ACE 5.2 on Redhat Linux 6.1, 7, and 7.1.
ACE has been ported to Windows NT, 2000 with Borland's C++Builder 5.
led the effort for this port. Riverace supports ACE 5.2 on this platform.
changes to allow ACE to work on Unixware 7.1 using gcc 2.95.2. Please
see the ACE-INSTALL.html file for specific information regarding this
ACE now works correctly on Solaris 8. It has been tested with the
Sun Workshop 5 and Forte 6 compilers, as well as gcc 2.95.2 and 3.0.
A number of people in the ACE user community contributed work towards
getting ACE ported to Mac OS X. The most prominent contributors are
John Michael Zorko.
Not everything is working perfectly yet, but with a little more help
from the community Mac OS X can become a first-class ACE platform.
If you are interested in having Riverace add Mac OS X to the supported
platforms list, please contact
a set of classes that implement a byte stream IPC mechanism over
shared memory. These classes can be used for very efficient
IPC between processes on the same host. Please see the
MEM_Stream_Test test program and the man pages for
ACE_MEM_Stream, ACE_MEM_Acceptor and
contributed ACE_OS wrapper emulations to enable the
ACE_OS::opendir, ACE_OS::readdir and
ACE_OS::closedir functions to work on Win32 platforms.
This allows the ACE_Dirent class to work as well.
When building DLLs on Win32, care must be taken to properly use the
import and export specifications for the library entrypoints.
ACE now provides a Perl script in bin/generate_export_file.pl
that can be used to generate the necessary header file for any project.
Instructions for its use are included in the script.
Jerry D. De Master
contributed additions to the Logging Strategy so it can be used to
limit log file size at any logging point
(i.e., application, client logging daemon, or server logging
daemon) by specifying the -i sample_interval_in_secs
and -m max_size_in_KB options for the
Logging_Strategy class in a svc.conf file.
added a set of
IPC wrappers encapsulating the OpenSSL SSL socket functions into
IPC stream classes that can be interchanged with other IPC classes in
ACE. These wrappers are in the ace/SSL directory and are built when the
ssl=1 option is specified on the make command or in your platform_macros.GNU
There are examples of the new classes' usage in
For more information on the SSL facility, please see
Please note that due to a limitation in OpenSSL (not ACE's SSL wrappers)
an SSL connection cannot be operated on simultaneously by multiple
These wrappers are officially experimental and may change in future
releases of ACE.
a simple, small-scale, reliable multicast protocol for ACE. It is located
in the ace/RMCast directory and its tests are in the tests/RMCast directory.
ACE_High_Res_Timer::gettimeofday_hr() is a new function
that returns the current time in a ACE_Time_Value object using the
high-resolution time source. This is intended to be used as the
time retrieval function for the ACE timer queues. Be sure to
call ACE_High_Res_Timer::global_scale_factor() (or instantiate
a ACE_High_Res_Timer object) before using it to correctly
convert the timer count to a ACE_Time_Value.
Two tests were modified to show how to use this new function.
tests/Timer_Queue_Test.cpp has an added test for using
ACE_Timer_Heap with high-resolution timer as the time source.
tests/Reactor_Timer_Test.cpp has an added option to run the test
using ACE_High_Res_Timer::gettimeofday_hr instead of the
ACE_OS::gettimeofday time retrieval. If any option is given to
the program it uses high-res, otherwise it uses ACE_OS::gettimeofday.
broke the dependency
of ACE_Log_Msg on the IPC wrapper facades by separating the
logging backend into a new class based on the virtual
ACE_Log_Msg_Backend class. The original IPC-based logging backend
is still available for forwarding log messages to logging servers. There are
also 2 new classes, ACE_Log_Msg_NT_Event_Log and
ACE_Log_Msg_UNIX_Syslog. These new backends cause log records
to be sent to the NT Event Log or the UNIX facility, respectively. They
are enabled by including the ACE_Log_Msg::SYSLOG value in
the flags argument to ACE_Log_Msg::open().
a new set of classes that implement support for a reference-counted
The format specifiers for ACE_Log_Msg::log() have been
extended for wide character support. For characters and strings, the
format options are now:
%c (print out an ansi character),
%C (print out an ansi string),
%s (print out an ACE_TCHAR * string),
%w (print out a wide character),
%W (print out a wide string).
The second parameter to ACE_OS::shutdown() is usually a decimal
value to specify which end(s) of a socket to shut down. Thanks to
Mike Curtis, ACE now
defines ACE_SHUTDOWN_READ, ACE_SHUTDOWN_WRITE,
and ACE_SHUTDOWN_BOTH to make use of this method more
Edan Ayal, and
all contributed to development of a new strategy class,
ACE_Bounded_Cached_Connect_Strategy, which provides a bound
on the cache which is checked before creating new handlers.
There is a new option for ACE's make scheme. stdcpplib can be
specified either in the platform_macros.GNU file or on the
command line. It defaults to 1 (enabled) on compilers/platforms that
support the standard C++ library. These include Sun Workshop 5 and Forte 6,
HP aC++ x.27 and higher, AIX Visual Age C++ 5. Note that if stdcpplib
is enabled, the ACE_IOStream class template is disabled. This
restriction will be lifted in a future version of ACE.
added a new method, ACE_Reactor::resumable_handler().
This indicates whether the application
can explicitly resume handlers or
not. Not all reactors allow this feature.
support for the addition of ACE_OS_Dirent::scandir()
which makes it possible to selectively pick which files in a directory
to iterate over.
This is used to support a new wrapper facade in
ACE_Dirent_Selector that encapsulates the scandir functionality.
added a new wrapper method for ACE_OS::select()
that uses ACE_Handle_Set pointers rather than fd_set
pointers. This was motivated by work Steve Huston and Doug did on
``C++ Network Programming: Resolving Complexity with ACE and Patterns.''
That book explains this wrappers motivation and usage.
new classes to implement intrusive lists. That is, lists that assume
their elements implement the next() and prev()
methods. ACE_Intrusive_List is the list class.
ACE_Intrusive_List_Node is a helper class that adds the
requirements of ACE_Intrusive_List to any other class.
added a new
send_n() method to the ACE_SOCK_Stream and
ACE_FILE_IO classes that sends a chain of
using the underlying OS gather-write operation to
reduce the domain-crossing penalty.
Thanks to ideas and code pointers from
a set of new ACE_Process_Options methods to encapsulate passing
handles to spawned processes. Motivation of this facility and an
example of its use is in C++ Network Programming, Volume 1:
Mastering Complexit With ACE and Patterns.
The source code for the logging server and client examples in
C++ Network Programming, Volume 1: Mastering Complexity with ACE
and Patterns is now included in the examples/C++NPv1 directory.
contributed a pair of new classes for reference-counted pointers.
ACE_Strong_Bound_Ptr implements support for a reference counted
pointer. Assigning or copying instances of an ACE_Strong_Bound_Ptr
will automatically increment the reference count of the underlying object.
When the last instance of an ACE_Strong_Bound_Ptr that references a
particular object is destroyed or overwritten, it will invoke delete
on its underlying pointer.
ACE_Weak_Bound_Ptr implements support for a weak pointer that
complements ACE_Strong_Bound_Ptr. Unlike
ACE_Strong_Bound_Ptr, assigning or copying
instances of a ACE_Weak_Bound_Ptr object will not automatically
reference count of the underlying object. What ACE_Weak_Bound_Ptr
preserve the knowledge that the object is in fact reference counted, and
thus provides an alternative to raw pointers where non-ownership
associations must be maintained. When the last instance of an
ACE_Strong_Bound_Ptr object that references a particular object
is destroyed or overwritten, the corresponding ACE_Weak_Bound_Ptr
instances are set to 0.
A large number of problems were fixed for version 5.2.
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.
A problem which previously manifested itself as intermittent failures
in the Timer_Queue_Test and MT_Reactor_Timer_Test
has been fixed.
There was a very subtle bug in
all versions of ACE_Reactor::register_handler. The problem
was that once the event handler has been successfully registered with the
Reactor, it is available for processing events. In the problem
case, input arrived from the client, the handler handled it, and
promptly closed down. All this happened in another thread
running the Reactor event loop, before the handler's reactor pointer
had been set. By the time the reactor tried to set the handler's
reactor pointer, event handler had packed up and gone home. Thanks
to Irfan Pyarali
for this fix.
Previously, if a ACE::send_n_i() call to send() failed
with EWOULDBLOCK, the method continually retried the send until it worked,
causing a large CPU usage spike. Now the method waits for the handle to
become writeable again before retrying the send. Thanks to
for reporting this.
The ACE_WFMO_Reactor class has been fixed to correctly redo the
upcall for an event handler callback method that returns 1.
There have been a large number of functionality and memory leak fixes made
to the ACE_Configuration class.
submitted a number
of fixes to allow the Reactor to support file descriptors numbering more than
FD_SETSIZE on platforms that support them (e.g. via
a large number of fixes and improvements to the POSIX async I/O proactor
framework for both POSIX and Solaris environments.
Note, even with these very important improvements to ACE, some platforms'
AIO implementations exhibit troublesome behavior. If you are considering
a multiplatform system using asynchronous I/O, please consult Riverace
In previous ACE releases, the behavior of ACE_OS::rename() when
the destination file existed was different - on UNIX/POSIX, the destination
file was replaced, while on NT/2000 the operation failed. This has been
remedied. The destination file is always replaced now. If you desire the
rename to fail in this case, there is a 3rd, defaulted, argument to
the method that allows passing in modifier flags to alter the behavior.
Supplying any flags value that does not include
MOVEFILE_REPLACE_EXISTING will cause the rename to fail as in
On calls to ACE_Future::set() from multiple threads, only one
will notify waiters. Thanks to
for this fix.
A number of fixes and improvements were made to the ACE_TP_Reactor
class to improve its performance and behavioral consistency. The
ACE_TP_Reactor will now dispatch one event when the leader
thread is woken up (a timer, notify, or I/O event). Note that this
improvement removes an implicit thread synchronization that existed in
previous versions of ACE_TP_Reactor. For example, previous
versions implicitly guaranteed that a timer expiration and an I/O event
would not be dispatched simultaneously for the same handler in different
threads. That simultaneous behavior is now possible.
fix that makes ACE_Service_Repository::remove() reentrant.
This enables the method to be called from another service's fini()
method that was called from remove().
In earlier versions of ACE, the ACE_Thread_Manager::spawn_n
method that takes a thread_id array did not take the
If a user activated a task and requested the thread IDs,
the threads would not be marked as belonging to the starting
ACE_Task object, which caused
them to be unaccounted for in subsequent calls to
ACE_Thread_Manager::wait_task. Fixed the problem
by adding the task argument to ACE_Thread_Manager::spawn_n()
and making sure the task pointer is passed in the ACE_Task::activate()
method. Thanks to Mervyn Quah
for reporting the bug.
Deadlocks under some conditions on UNIX were fixed by changing
the ACE_Process_Manager class to use the
ACE_Reactor::notify() capability from the signal
handler. This allows the signal handler to notify the reactor
(over a pipe) that the signal should be processed. This is done
completely without MT locks. If
ACE_HAS_REACTOR_NOTIFICATION_QUEUE is defined,
ACE_Select_Reactor_Notify::notify_queue_lock_ is now made a
Thanks to Roger Larsson
for contributing these fixes.
The find() methods in the ACE string classes were fixed so that
if a match is found, they return the index from start of string, not from
the passed pos argument. This matches the C++ string standard,
which was the model for these classes. Thanks to
for this fix.
The ACE_Process_Mutex class was not properly serializing
access on all platforms. This has been fixed.
made a number of improvements to ACE_TP_Reactor to more fairly
dispatch events across threads in the thread pool and fixed a possible
ACE_High_Res_Timer was fixed to work properly
with very fast clocks (> 1GHz). Thank you to
identifying the problem and coming
up with a good solution.
In an effort to further the ACE subsetting effort, a number of inter-layer
dependencies have been broken. This did not introduce any API changes; however,
some source code that relied on source files being implicitly included at
compile time (most notably ace/Log_Msg.h) will not compile
at ACE 5.2. To fix this, explicitly include the needed header file(s)
in your source code.
Previous versions of ACE contained the man pages for that release. The
man page generation scheme has been vastly improved, and now uses
Doxygen, which generates quite a bit more information than the old
system did. The man pages are now available on the web - see
The implementation of ACE_Acceptor::open() and
ACE_Acceptor::accept_svc_handler() were modified so
that the peer acceptor's handle is set into nonblocking mode.
This is a safeguard against the race condition that can
otherwise occur between the time when select() indicates that a
passive mode socket handle is ready and when ACE calls accept().
During this interval, the client can shutdown the connection, in
which case, the accept() call can hang.
This change affects the ACE_SOCK_Stream, ACE_TLI_Stream
and ACE classes.
In order to make the return values of the recv_n and send_n
methods match the return values of the send and recv
methods, the return values were changed to:
To properly convey the number of bytes transferred on timeout, error, and
EOF conditions, a new, optional argument is added to the end of each
function's signature. The argument is size_t *bytes_transferred,
and it defaults to 0 (do not return the number of bytes transferred).
- On complete transfer, the number of bytes transferred is returned.
- On timeout, -1 is returned, errno == ETIME.
- On error, -1 is returned, errno is set to appropriate error.
- On EOF, 0 is returned, errno is irrelevant.
Although code that worked with previous ACE releases will compile correctly,
it is important to review your usage of these methods to insure that you
correctly react to the new return values.
To avoid inconveniencing Win32 users without Pharlap, all of the Pharlap
configurations in the ACE tests were moved to their own project files in
the new tests/pharlap directory.
Herculean effort to greatly improve the support for wide character and
Unicode in ACE. Previous versions of ACE included very non-intuitive
support for wide character and Unicode. This change makes it very
sensible and straight-forward. However, this involved the following changes
that you should be aware of:
- Standardized wide char support to the following macros:
Note also that whether or not ACE_USES_WCHAR is defined, both
wide and narrow versions of the string operations will be available
as long as ACE_HAS_WCHAR is defined.
- ACE_HAS_WCHAR - if not defined, ACE will not use the
type wchar_t or provide any of the functions that use it.
- ACE_USES_WCHAR - if defined, ACE will use wchar_t
instead of char for its strings (but not its buffers).
- Removed all the ASYS_* macros (besides ASYS_INLINE). So
all code using ASYS_TEXT and ASYS_TCHAR should now use
ACE_TCHAR. And unlike their predecessers, these will turn into
wide character versions when ACE_USES_WCHAR is defined.
- Removed the macros ACE_HAS_WCHAR_TYPEDEFS_USHORT and
ACE_HAS_WCHAR_TYPEDEFS_CHAR since ACE will not depend on what
wchar_t defaults to.
- Since ACE_WString was changed, everything using it will now
not be available when ACE_HAS_WCHAR is not defined.
The Logging Strategy class has been moved from the netsvcs component
into the ACE library to facilitate easier use of its power.
A new method was added to access the Reactor's timer queue. Also
renamed the accessors timer_queue(ACE_Timer_Queue *) and
ACE_Timer_Queue *timer_queue() to be more consistent with ACE
naming conventions. The old set_timer_queue() method is still
available for backwards compatibility, but it is deprecated and will be
removed in a future ACE release.
The ACE_Configuration class's text import/export functionality was moved to
new classes explicitly supporting import/export for both the Win32
registry-like format and a INI format. The
ACE_Configuration::export_config were changed to use the
Win32 registry-like file format, and both functions are deprecated in favor
of the new classes:
The ACE_Registry_ImpExp class has the ability to read a configuration
file exported in ACE 5.1. However, when the configuration is exported, it
will be converted to the new Registry export file format.
The Linux platform's official config.h file is now
ace/config-linux.h and the platform_macros.GNU file is
include/makeinclude/platform_linux.GNU. The ``lxpthreads'' versions
of the config and macros files are deprecated and will be removed. Threads
is enabled by default in the new files.
The ACE build now assumes that Winsock 2 is enabled unless the config.h
file explicitly disables it by defining ACE_HAS_WINSOCK2 to be 0.
This will affect users on Windows 95. Windows 95 users must either
install Winsock 2 (available at no charge from Microsoft) or disable
Winsock 2 before building ACE.
contributed fixes to ACE::timestamp() so it works identically
on all platforms. Also, a 3rd (optional) argument was added. The argument
is return_pointer_to_first_digit. If it is 0 (the default),
the method returns a pointer to the space before the time, else it returns
a pointer to the beginning of the time portion.
Also, the ACE::timestamp() method now also returns a string
with the date that also contains the year. Thank to
for reporting this.
The ACE_Token_Collection, ACE_Mutex_Invariants,
ACE_Remote_WLock and ACE_TSS_Connection classes
are no longer built by default when ACE is built. The classes are
not widely used, so were moved aside to save space. To build them
into ACE, add #define ACE_HAS_TOKENS_LIBRARY to your
config.h file before building ACE.
Additionally, the token server functionality in the netsvcs component
are also not built unless ACE_HAS_TOKENS_LIBRARY is defined.
In previous versions of ACE, shared libraries were built with a ``shr''
suffix. Library naming has been changed to be consistent with IBM
guidelines and practice. Shared libraries built using ACE's configuration
files will now be built into a shared object file name shr.o and
then included into an archive file. Thus, the shared library name of the
main ACE library is libACE.a. Nonshared (archive) libraries
are named with a ``_ns'' suffix (e.g., libACEns.a).
There is a new configuration macro available for config.h. If
ACE_NO_WIN32_LEAN_AND_MEAN is set, ACE will not
define WIN32_LEAN_AND_MEAN before including windows.h.
This is needed for code that makes use of non-lean things, such as COM,
that only get included when WIN32_LEAN_AND_MEAN is
The ACE_Timer_Heap class's free IDs list was changed from a stack
to a round-robin list. Newly-allocated IDs keep increasing til
there aren't any more, then wrap around to the lowest numbered
free ID and start again. This is a ease-of-use improvement to
help applications catch their timer-related errors easier,
which is apparantly important, especially in multi-threaded
applications. ACE_Timer_Heap is the most common timer mechanism
used in ACE.
A new parameter was added to the
constructor of the ACE_Reverse_Lock class. The
parameter is used to indicate which acquire() method will be
called on the real lock when the release() method is called on
the reverse lock. REGULAR indicates the acquire() method,
READ indicates the acquire_read() method, and
WRITE indicates the
acquire_write() method. Note that the try_*() methods
represented here because we have to make sure that the release()
method on the reverse lock acquires a lock on the real lock.
Thanks to Edan Ayal
The behavior of ACE_Log_Msg::log() was extended so that all printf
formatting conversion specifiers can be used with all legal
ACE_Log_Msg format characters. This allows the caller to line
up columns on any field, like line number or program name, or
thread ID. Thanks to Paul Caffrey
motivating this extension.
made a series of
improvements to the Service Configurator component to make the parser
reentrant and thread-safe.
All ACE header files now include alignment guards. This is especially
helpful to Windows developers because they no longer have to be careful
to set compiler alignment options to match ACE, or other programs developed
The default file and directory permission masks for UNIX were changed
from 0666 and 0777 to 0644 and 0755, respectively. This is a security
improvement to prevent files and directories getting created with
wide write permissions by default.
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 Bound_Ptr_Test fails to compile using IBM C/C++ 3.6.6. This is
believed to be a compiler problem.
The Refcounted_Auto_Ptr_Test program dumps core; this is a compiler
problem as well.
The Config_Test fails on AIX 4.3 when built with Visual Age C++ 5.
This is due to a compiler problem.
When a new thread is created by Windows NT in response to starting an NT
the thread has no use of ACE_Log_Msg. Unlike an ACE-started thread,
info is not set up in the new thread, and logging has no affect.
To work around this problem, the thread has to explicitly open
ACE_Log_Msg before logging anything.
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''
ACE Version 5.2 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 ace52.tex
The translation was initiated by Steve Huston on 2002-01-10