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.


Contents

New Features in Version 5.3

ACE_RW_Process_Mutex Can Create a Unique Name

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.

New Allocator Support for ACE_Activation_Queue

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.

ACE_Time_Value ++ and - Operators

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.

ACE_Get_Opt Support for Long Options

The ACE_Get_Opt class now supports both long and short options. Please see the man page for complete details.

New Class ACE_Asynch_Connect

Alex Libman contributed... fill this in.

New ACE_Log_Msg Format Options M and @

The ACE_Log_Msg::log() method has 2 new formatting options.

ACE_Arg_Shifter Now Takes Both const and non-const

The ACE_Arg_Shifter class has a new constructor. It now can accept both const and non-const arrays for arguments.

ACE_GUARD_ACTION and ACE_GUARD_REACTION Macros

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 Ported to Windows CE .NET

ACE now works on both Windows CE 3 with the PocketPC 2002 SDK, and on Windows CE .NET (version 4.x).

ACE Ported to Mac OS 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 Ported to Windows XP 64-Bit Edition

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 Ported to Windows, Visual C++ .NET (aka VC7)

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.

ACE Now Works on Windows with MingW

Thanks very much to Johnny Willemsen for driving the effort to make ACE work under MingW.

IPv6 Support Added

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.

ACE_Get_Opt Long Option Support

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.

ACE_Message_Queue Enqueue/Dequeue Options

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.

ACE_Log_Msg Custom Backends

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.

C++NPv2 Example Code

All of the example code from C++ Network Programming, Volume 2 are included in the ACE_wrappers/examples/C++NPv2 directory.

ACE_Dev_Poll_Reactor

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.

XML-Based Service Configurator

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.

ACE_Message_Queue::pulse() Method and PULSED State

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.

MakeProjectCreator Tool

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()

ACE_OS::atop (const char *s) is a new method that attempts to convert the character string s to a void *.

ACE_OS::num_processors(), num_processors_online()

These two new methods were added for determining the number of CPUs available on a system. Thanks to Christopher Kohlhoff for these.

New, Faster ACE_Atomic_Op

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.

Enhanced Support for Joining Multiple Multicast Groups

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.

ACE_Process::return_value() Method

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.

Problems Fixed in Version 5.3

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.

ACE_Date_Time Reports Correct Year and Month

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.

ACE_SOCK_Dgram_Mcast::unsubscribe

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.

Corrected Solaris 2.6, 7, 8 Configuration

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.

ACE_TTY_IO::control Timeouts

The specification of timeouts on Windows for ACE_TTY_IO::control has been fixed. Thanks to Lars Steubesand for reporting this.

Race Condition/Deadlock in Service Config Parsing

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.

ACE_LSOCK::recv_handle

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.

ACE_Ini_ImpExp:import_config Correction

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.

Mac OS X Improvements

Added new fixes to MacOS X configuration files. Thanks to John Michael Zorko and Fikri Pribadi for contributing this.

ACE_OS::llseek Improved on Windows

The Windows implementation of ACE_OS::llseek() has been improved. Thanks to Doron Rajwan for reporting this.

ACE_Select_Reactor Correctly Handles Notification Failure

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.

ACE_OS::tempnam with Borland C++Builder

The ACE_OS::tempnam() method has been fixed to build correctly with Borland C++Builder with wide character support enabled.

SSL Classes Improved

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.

ACE_SOCK_Dgram_Mcast::unsubscribe() Fixed

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.

ACE_NT_Service::state() Fix

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.

ACE Logging Now Works in NT Service-Created Thread

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.

C++NPv1 Examples Fixed

The example code for C++ Network Programming, Volume 1, originally released with ACE 5.2, has been corrected thanks to many diligent readers.

Important Changes in Version 5.3

ACE_Date_Time Now Reports Microseconds

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.

Easier to Set Source/Program Name for syslog/Event Log

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.

ACE_TP_Reactor::remove_handler

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.

ACE_OS::llseek Is a Static Method

The ACE_OS::llseek() method is now static, as it was originally intended to be.

ACE_Time_Value += and -= Now Return Reference to Self

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.

ACE_SSL_SOCK_Stream Methods Removed

The ACE_SSL_SOCK_Stream::reactor() and handler() methods were removed. Design changes internal to the SSL classes rendered these methods unneeded.

ACE_Time_Value Operator Method Return Types

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.

Orbix Supporting Classes Removed

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.

ACE_SPIPE_Acceptor Handle Value

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.

Changed config.h File for HP-UX 11

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.

Support for AIX 3.2.5 and HP-UX 9 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.

ACE_Proactor Event Loop Methods

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 *).

ACE_Reactor Event Loop Hook Method Argument

The REACTOR_EVENT_HOOK function type now accepts a pointer pointer to the Reactor instance calling it.

ACE_WFMO_Reactor Dispatch Order

The ACE_WFMO_Reactor event dispatch order was changed to match the ACE_Select_Reactor dispatch order. The order now is:

Proactor Framework Improvements

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.

OS-specific Thread Function Return Type

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().

API Type Changes

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:

PACE Removed from ACE

The ``POSIX ACE'' effort known as PACE, has been discontinued and removed from ACE.

ACE_Configuration Method Return on Error

The ACE_Configuration methods now always return -1 and an errno value instead of returning various negative integers depending on the error.

ACE_MMAP_Memory_Pool_Options File Protection

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.

Mutex Protection Mode

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.

ACE_Malloc_T Lock Can Be Passed

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.

Known Problems With Version 5.3

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.

ACE_NT_Service Won't Compile if VC_EXTRALEAN is Defined

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.

ACE_IOStream Class Does Not Work With Standard iostreams

The ACE_IOStream class template has not been updated to work with standard iostreams implementations. It only works with ``old'' iostreams.

Proactor_Test Times Out on Some Platforms

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.

About this document ...

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