ACE Version 5.3 Release Notes
Riverace Corporation
January 15, 2003
This document describes the additions, changes, and
fixes which were made to ADAPTIVE Communication Environment (ACE)
for version 5.3.
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. See the
Riverace website
for details.
ACE is discussed in the following forums:
The book C++ Network Programming, Volume 2: Systematic Reuse with
ACE and Frameworks (ISBN 0-201-79525-6) describes the major frameworks
in ACE and matches ACE version 5.3.
Additionally, the Doxygen-generated documentation for ACE has been
greatly improved through many efforts, most notably those of
Johnny Willemsen.
ACE_RW_Process_Mutex now has the ability to create a
unique name if the caller doesn't supply one. Thanks to
Tom Wagner
for suggesting this.
The ACE_Activation_Queue class now has support for two
ACE_Allocator items that will control how the message blocks
and data blocks are allocated. Thanks to
Gil Rapaport
for contributing this.
The ACE_Time_Value class now offers both prefix and postix versions
of the ++ and - operators. The operators increment and
decrement, respectively, the microseconds part of the time. This allows
ACE_Time_Value to be used with the ACE_Atomic_Op class.
The ACE_Get_Opt class now supports both long and short options.
Please see the man page for complete details.
Alex Libman contributed... fill this in.
The ACE_Log_Msg::log() method has 2 new formatting options.
- 'M' will display the name of the message's log priority. Thanks to
Vladimir Chovanec
for this addition.
- '@' takes a pointer argument and displays the pointer in
hexadecimal notation. Thanks to
Krishnakumar B
for this
addition.
The ACE_Arg_Shifter class has a new constructor. It now can accept
both const and non-const arrays for arguments.
Two new macros were added to give more flexibility in dealing with
potential failure conditions when using the ACE_Guard-related
macros. ACE_GUARD_ACTION and ACE_GUARD_REACTION
allow customized code blocks to be used for success and failure conditions
when acquiring the guard. See the ace/Global_Macros.h file
for syntax. Thanks to
Boris Kaminer
for suggesting these.
ACE now works on both Windows CE 3 with the PocketPC 2002 SDK, and on
Windows CE .NET (version 4.x).
ACE has been mostly ported to Apple Mac OS X 10.2. The Apple components
cause some difficulty, but Apple is investigating. Many thanks to
John Michael Zorko
and
Craig Rodrigues
for working
very hard on this project.
ACE has been ported to work on Windows XP 64-bit Edition. This port
uses the Microsoft Platform SDK compiler; the Visual C++ environment
is not able to generate 64-bit code. The ace_dll64.mak NMAKE
file should be used to build ACE. The config-win32.h file should
be used for your config.h file.
Thank you to
Justin Michel
who
reimplemented the ACE_Timer_List and ACE_Timer_Wheel
classes to remove dependencies on type size assumptions, allowing this
port to be completed quicker.
ACE has been ported to Microsoft Visual C++ .NET, also known as
Visual C++ 7. As with previous Visual C++ versions, users should use
config-win32.h as the basis of their config.h file.
Compiler-specific settings are automatically detected.
Thanks very much to
Johnny Willemsen
for
driving the effort to make ACE work under MingW.
IP version 6 (IPv6) support has been added to ACE. To enable the IPv6 code
for a build, add #define ACE_HAS_IPV6 to your config.h file.
Additionally, if your build with IPv6 enabled must also run on systems where
the IPv6 support in the kernel is not actually turned on (for
example, Redhat Linux 7 by default), also add this to your
config.h file: #define ACE_USES_IPV4_IPV6_MIGRATION
Many thanks to Nokia for funding this addition to ACE.
Thanks to Don Hinton
for
adding support for long options to ACE_Get_Opt. This functionality
closely mimics that provided by getopt_long(3c). Please see
the documentation for this class, and the description of it in
C++ Network Programming, Volume 2 for examples.
The ACE_Message_Queue class can now be asked to enqueue
items based on the message deadline, and to dequeue based on
priority, message deadline, and from the end of the queue.
It is now possible to install custom backends to ACE_Log_Msg
to provide customized handling of logged messages. Custom backends are
per-process entities, whereas logging callbacks are per-instance
entities. Thanks to
Boris Kolpackov
for this feature.
All of the example code from C++ Network Programming, Volume 2
are included in the ACE_wrappers/examples/C++NPv2 directory.
Ossama Othman
contributed a
new reactor implementation based on the /dev/poll device.
This new reactor is experimental in ACE 5.3. It should provide much
better performance than ACE_Select_Reactor when many I/O handles
are being demultiplexed.
There is a new XML format for configuring services in the ACE Service
Configurator framework. The new format is described in C++NPv2.
This new format is not enabled by default; the traditional svc.conf file
format is still the default in ACE 5.3.
To enable ACE to use the new XML-based Service Configurator, add
#define ACE_HAS_XML_SVC_CONF to your config.h file and rebuild ACE.
The XML-based format will likely become the default in a future ACE
version.
Douglas C. Schmidt
added a new pulse() method. When called, the queue changes to
the new PULSED state and any threads blocked on enqueue or dequeue
operations to return immediately as if the queue had been deactivated.
However, all operations initiated in the PULSED state behave as if
the queue were in the ACTIVE state. See C++NPv2 chapter 6 for a description
and example of this new facility.
Many thanks to OCI for contributing the MakeProjectCreator tool. This
is located in ACE_wrappers/bin/MakeProjectCreator. The tool allows
automatic creation of Makefiles, Visual C++ 6 and 7 workspaces/projects,
eMbedded Visual C++ 3 and 4 workspaces and projects, and NMAKE files from
a single workspace/project definition. The MakeProjectCreator tool is
used to generate the workspace and project files for Visual C++ 7 and
eMbedded C++ for Windows CE in ACE 5.3.
ACE_OS::atop (const char *s) is a new method that attempts to convert
the character string s to a void *.
These two new methods were added for determining the number of
CPUs available on a system. Thanks to
Christopher Kohlhoff
for these.
Added a new fast, lightweight ACE_Atomic_Op template specialization
for x86 platforms that uses the architecture's atomic integer
primitives. It currently supports Win32 using MSVC6 or BCB, and g++
for (in theory) all x86 operating systems. It selects the
appropriate implementation for single- or multi-CPU systems at
runtime, based on the return value of the ACE_OS::num_processors
function added above.
Note that the ACE_Atomic_Op::mutex() operation has been
deprecated (and is not supported for the new specialization). If
you need this functionality, consider using the ACE_Atomic_Op_Ex
template instead.
Explicit template instantiations for
ACE_Atomic_Op<ACE_Thread_Mutex,long> and
ACE_Atomic_Op_Ex<ACE_Thread_Mutex,long> were added to ACE.
Programs using ACE should no longer explicitly instantiate these classes.
ACE_SOCK_Dgram_Mcast now has enhanced support for join()'ing
multiple multicast groups. The constructor
now offers finer control over a bind()'ing to an address or
interface. Appropriate default behavior has been specified,
but note that due to issues on Linux, portable code should not
join() more than one multicast group per instance.
An open() method has been added/exposed. If not explicitly
called, it will be implicitly called by the first join(), and
will bind() the address if the OPT_BINDADDR_YES options was
specified in the constructor.
Error handling has also been enhanced. For instance, if
OPT_BINDADDR_YES has been specified (the default on Linux),
additional join()'s will fail since the socket gets bound on
the first call to open() or join(). Previously, subsequent
calls to join() would silently fail, i.e., the call succeeded
but only datagrams sent to the first, bound address where
actually delivered.
If ACE_SOCK_DGRAM_MCAST_DUMPABLE is defined, a list of all
subscribed groups is maintained and can be dump()'ed, although
access to this list is not public.
Added new join()/leave() methods that remove unused, deprecated
protocol_family and protocol arguments. These values can be
determined on the fly. The old subscribe()/unsubscribe()
methods have been deprecated and are now implemented in terms
of join()/leave() respectively.
The unsubscribe(void) method has also been deprecated. It was
designed to allow the caller to unsubscribe/leave() all
groups at once, but since a list was never kept (and still
isn't unless ACE_SOCK_DGRAM_MCAST_DUMPABLE is defined) only
the last group join()'ed was ever left. A better way would
be to either keep track of you own groups and call leave()
for each, or let the dtor close() the socket which automatically
unsubscribes from all groups.
Some IPv6 support has been added either directly or by removing
the need for the caller to handle it (see join()/leave() above),
although the internal calls to setsockopt() are still hard wired
for IPv4.
Added a new method return_value() which returns
the actual value returned or specified at exit by the child process.
The exit_code() accessor returns the raw exit status returned by
the system APIs and the value is OS dependent. Changed the
exit_code() mutator to be a proctected method.
A large number of problems were fixed for version 5.3.
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
see the
ACE Bugzilla page.
The ACE_Date_Time class was reporting the year value as years since 1900.
This has been corrected to report the actual year value. Also, the month
value was fixed to report the actual monthy, not the 0-indexed month.
The ACE_SOCK_Dgram class allows an application to subscribe a
single socket to many multicast groups. However, the unsubscribe operation
failed to work with more than one group. For some strange
reason it was storing the first multicast group subscription in
a class member and using that member in all the paths for the
unsubscribe methods.
This has been fixed so the unsubscribe(const ACE_INET_Addr&,...)
method works as advertised, that is, unsubscribe the given multicast
address, not the stored one. As an added benefit the method is
now reentrant. The unsubscribe(void) method works as before.
The config.h settings for Solaris 2.6, 7, and 8 no longer explicitly
set _POSIX_C_SOURCE to 199309L __EXTENSIONS__. They
aren't needed to pick up shm_open as previously believed, and
they interfere with availability of some Solaris/C9x functions.
The specification of timeouts on Windows for ACE_TTY_IO::control
has been fixed. Thanks to
Lars Steubesand
for reporting this.
Ossama Othman
made a number of
important fixes to service configuration parsing to fix a race condition
and potential deadlock while processing service configuration
directives at program startup.
The ACE_LSOCK::recv_handle() was returning success
without setting the I/O handle. This has been fixed.
Thanks to Rick Ohnemus
for reporting this.
Fixed a bug in ACE_Ini_ImpExp::import_config where a
check of a pointer was made rather than the character pointed to
by the pointer. Thanks to
Juan Jose Comellas
for reporting this.
Also fixed a bug where equals signs were not handled correctly even if
quoted. Thanks to
Glen Coakley
for
this fix.
Added new fixes to MacOS X configuration files. Thanks to
John Michael Zorko
and
Fikri Pribadi
for contributing this.
The Windows implementation of ACE_OS::llseek() has been
improved. Thanks to
Doron Rajwan
for reporting this.
ACE_Select_Reactor was fixed to be more careful about error
handling while dispatching notification handlers. If a failure occurs,
it now returns -1, rather than erroneously adjusting the count of the
number of handlers dispatched. Thanks to Don Hinton for reporting this.
The ACE_OS::tempnam() method has been fixed to build correctly
with Borland C++Builder with wide character support enabled.
A number of important fixes were made to ACE's SSL wrapper classes. These
include correct data handling at connection startup and improved handling
of iovec-based transfer methods.
The ACE_SOCK_Dgram_Mcast class allows application to subscribe
a single socket to many multicast groups. However, the
unsubscribe() method failed to work with more than one group.
It would only unsubscribe the first group subscribed.
The unsubscribe(const ACE_INET_Addr&,...) method now
works as adversited, i.e. it unsubscribes the specified multicast
address, not the first one.
A bug in previous versions caused calls to
ACE_NT_Service::state() while the service is stopped to corrupt
the internal status variables of the service. If the control mask was set to
SERVICE_ACCEPT_STOP in the constructor, the call to state would
cause this mask to be reset (if the service is not running).
This ultimately resulted in an NT Service that could be started but
not stopped. Thanks to
Kyle Brost
for
providing this fix.
When using the ACE_NT_Service class, the thread created by
Windows in response to starting a service can now use the ACE logging
facility without explicitly opening the thread's ACE_Log_Msg
instance. This fixes Bugzilla entry 82.
The example code for C++ Network Programming, Volume 1, originally
released with ACE 5.2, has been corrected thanks to many diligent readers.
ACE_Date_Time now uses ACE_OS::gettimeofday for the time
source. This gets both the seconds-since-epoch value (from which
the date and time are calculated) and the microseconds value. Previously,
the microseconds value was undefined.
The ACE_Log_Msg::open method was changed so that it will open
a SYSLOG backend (either UNIX syslog or NT Event Log depending on platform)
even if the logger key argument is 0. If the logger key argument is
0 (not specified) the previously-set program name is used as the source
identifier for the SYSLOG backend.
Thank you to
Christopher Kohlhoff
for
helping to get this behavior working correctly with the
ACE_Logging_Strategy class.
The ACE_TP_Reactor class now implements its own version
of the remove_handler() method. Previously, the version
inherited from ACE_Select_Reactor was used. That
implementation has a problem in the TP Reactor case. It tries to call
handle_close() (an upcall) as one of the calls after holding
the token. This was asking for trouble. This could lead to deadlocks as
mentioned in [BUG ID 1055].
The method in the TP_Reactor now calls remove_handler() on the
Select Reactor (its base class) with a DONT_CALL flag. Then it
calls ACE_Event_Handler::handle_close() on the event handler
if the caller did not pass in the DONT_CALL mask. This two
step process would get around the problem that was mentioned before.
Thanks to Graeme Clark
for reporting the problem and testing this fix.
The ACE_OS::llseek() method is now static, as it was originally
intended to be.
The ACE_Time_Value::operator+= and ACE_Time_Value::operator-= operators
now return a reference to the object operated on rather than a void.
This makes ACE_Time_Value's behavior consistent with other objects
offering these operators.
The ACE_SSL_SOCK_Stream::reactor() and handler() methods
were removed. Design changes internal to the SSL classes rendered these
methods unneeded.
The return values of ACE_Time_Value::operator+= and
operator-= were both changed from void * to
ACE_Time_Value &. Also, added overloaded operator++ and
operator-. This is all to make this stuff work better with
ACE_Atomic_Op. Thanks to
Kelly F. Hickel
for suggesting this.
The ACE classes, tests, and examples related to Orbix have been removed.
Iona does not sell or support the Orbix versions (2.x and 3.x) these
classes worked with.
ACE hasn't been updated to work with newer Orbix releases, and the preferred
ORB product with ACE is now TAO.
For Windows, ACE_SPIPE_Acceptor now uses the event handle
instead of the pipe handle for the handle value stored in the parent
ACE_IPC_SAP class. The pipe handle is pretty useless for doing
anything like detecting when the pipe connect is done - the
event handle is what's really useful there, and it stays
consistent across accepts, while the pipe handle changes. This
change allows the get_handle() value to be registered with the
Reactor framework, albeit for signal, not input.
When building ACE on HP-UX 11.x, use config-hpux-11.00.h,
not config-hpux-11.x-hpc++.h. The latter has been removed.
The configuration files for building ACE on AIX 3.2.5 and HP-UX 9.x
have been removed. These platforms are no longer supported by their vendors
and the compilers needed for ACE don't support them either.
The ACE_Proactor event loop control methods are now per-instance
methods. The older static event loop control methods are still present
for backwards compatibility; however, new code should use the per-instance
methods instead.
The ACE_Proactor::proactor_run_event_loop() method now takes
an optional hook function pointer defined as
int (*PROACTOR_EVENT_HOOK)(ACE_Proactor *).
The REACTOR_EVENT_HOOK function type now accepts a pointer
pointer to the Reactor instance calling it.
The ACE_WFMO_Reactor event dispatch order was changed to
match the ACE_Select_Reactor dispatch order. The order now is:
- FD_WRITE
- FD_CONNECT
- FD_OOB
- FD_READ
- FD_CLOSE
- FD_ACCEPT
- FD_QOS
- FD_GROUP_QOS
Many thanks to Alex Libman
for
contributing many fixes and improvements to the ACE Proactor framework.
These have helped to improve its functionality and stability across a
number of platforms. In addition to improving the existing Proactor classes,
Alex also contributed the new ACE_SUN_Proactor, which uses the
Solaris native aio calls, and the ACE_POSIX_CB_Proactor class, which
uses the POSIX completion callback method to learn of completion events.
These two new proactor implementation classes are experimental in ACE
5.3, so they must be explicitly created and assigned to an
ACE_Proactor class to be used.
Alex also contributed the new ACE_Asynch_Connect class, allowing
asynchromous socket connect operations. All of the proactor framework
additions are described in C++NPv2.
The ACE_THR_FUNC definition now incorporates the platform's
native thread function return type (DWORD on Windows, void* on most others).
The type itself is defined as ACE_THR_FUNC_RETURN and must now be
used as the return type for thread functions spawned using low-level
thread spawn methods in ACE. This does not affect
ACE_Svc_Handler::svc().
The port of ACE to Windows XP 64-bit Edition forced correction and alignment
of integer type usage. The following APIs have changed as a result:
- ACE_Activation_Queue::method_count() changed return
type from int to size_t.
- ACE String classes: npos changed from int to
ssize_t.
- ACE String classes: operator[] slot argument
changed from int to size_t.
- ACE String classes: strstr(), find(),
rfind() return type changed from int to ssize_t,
and the pos argument changed from int to size_t
(ssize_t for rfind()).
- ACE_Message_Queue::message_count() return type changed
from size_t to int.
- ACE_SOCK_*, ACE_FILE_IO, ACE_SPIPE_Stream:
All iovec-enabled methods (recvv*, sendv*)had the iovcnt
argument changed from size_t to int.
- ACE_UPIPE_Stream::send/recv: Changed return value
from int to ssize_t.
- textttACE_Log_Msg::log_hexdump(): Changed size argument
from int to size_t.
- textttACE::format_hexdump(): Changed size argument
from int to size_t and the return type from
int to size_t.
- Proactor framework: All byte-count related arguments changed from
u_long to size_t.
- ACE_SOCK_Dgram::send(): Address length changed from
size_t to int.
- ACE_Thread_Strategy n_threads argument changed from
size_t to int.
- ACE_ARGV::argc() type changed from size_t to
int. Also in ACE_OS::string_to_argv().
- ACE_Thread_Manager::count_threads(): Changed return value
from int to size_t.
- ACE_Thread::spawn_n(): Changed return type from
int to size_t.
- ACE_Semaphore::release(): Changed the release count from
size_t to u_int.
- ACE_Configuration::set_binary_value(), get_binary_value():
Changed length argument from u_int to size_t.
The ``POSIX ACE'' effort known as PACE, has been discontinued and removed
from ACE.
The ACE_Configuration methods now always return -1 and an errno
value instead of returning various negative integers depending on the error.
An optional file_mode argument was added to
ACE_MMAP_Memory_Pool_Options to set the protection mode on
the mapped file, if it is created; defaults to ACE_DEFAULT_FILE_PERMS.
The ACE_Process_Mutex constructor now takes an optional
mode_t argument to set the backing store mode (for ACE_Mutex use)
or the mode for the System V semaphore, when it's used. Additionally,
the ACE_Mutex constructor now takes an optional mode
to set backing store protection for Pthreads process mutex case,
where memory must be allocated to hold the mutex.
A new constructor was added to ACE_Malloc_T that
accepts an ACE_LOCK pointer instead of a ACE_TCHAR *lock_name.
This allows someone to form an ACE_LOCK externally and supply
it to the ACE_Malloc_T object. This is useful if special
permissions need to be set on the lock, such as the mode_t for
ACE_Process_Mutex.
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.
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''
iostreams.
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.
ACE Version 5.3 Release Notes
This document was generated using the
LaTeX2HTML translator Version 2K.1beta (1.47)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 ace53.tex
The translation was initiated by Steve Huston on 2003-01-16
Steve Huston
2003-01-16