ACE Version 5.4 Release Notes

Riverace Corporation

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 Riverace website for details.

ACE is discussed in the following forums:


Contents

New Features in Version 5.4

ACE_TEXT_ALWAYS_WCHAR Macro

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.

New Platform Ports

ACE was ported to the following platforms:

MakeProjectCreator--MPC

OCI 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 executable projects.

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 http://download.ociweb.com/TAO-1.3a/TAO1.3aMakeProjectCreator.pdf.

Codeset Registry

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.

Stream Control Transmission Protocol Support

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 in ACE_wrappers/performance-tests/SCTP.

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.

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.

ACE_Get_Opt Methods

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.

ACE_Configuration Unnamed Keys

Added the ability for ACE_Configuration to have a default, or unnamed, key. This is done with the help of a new validate_value_name() method 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.

GNU Autoconf Support

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 ACE_wrappers/ACE-INSTALL.html file.

IPv6 Support for UDP Multicast

IPv6 support, first added in ACE 5.3, was completed. The main addition is support for UDP multicast over IPv6 for Linux. Thanks to Brian Buesker for contributing this.

ACE_Vector Operators == and !=

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.

ACE_Vector_Iterator

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 area.

Examples from The ACE Programmer's Guide

The source code examples from The ACE Programmer's Guide are now available in ACE_wrappers/examples/APG.

Problems Fixed in Version 5.4

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 see the ACE Bugzilla page.

ACE_NT_Service::wait_for_service_state() Now Uses wait_time

The ACE_NT_Service::wait_for_service_state() method was enhanced to use the passed wait_time parameter. Thanks to Theo Landman for contributing this fix.

Memory Leak in ACE_Process_Manager::spawn()

Kobi Cohen-Arazi contributed a fix to release dynamically allocated memory in ACE_Process_Manager::spawn() if the spawn operation fails.

Corrected XML Parser Callback Correction

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.

ACE_Vector::resize() Off By One Fixed

Denis Parnaland submitted a fix for the ACE_Vector::resize() method. Previously, the last item in the vector was lost during the resize.

ACE_Stream_Tail::put() Return Value

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 Jody Hagins for help with this.

Debug Builds with IBM Visual Age C++ Didn't Use -g

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.

ACE_SPIPE_Stream Handle Passing

Phil Mesnier 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 closes it.

ACE_SSL_SOCK_Connector and Timeouts

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.

Event Handler That Registers During its Shutdown

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 been fixed.

Wide-Character Support

A number of wide-character related fixes were made that make wide-character applications much easier on Windows and Linux.

ACE_Thread_Manager Shutdown Crash

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 protected]> for suggesting the fix. [Bug 1505]

Important Changes in Version 5.4

OS Layer Reorganized

Don Hinton led a 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 differences.

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:

Header File Dependencies Lessened

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".

Reactor Framework Changes

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 Reactor.

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.

Reactors will now call new ACE_Event_Handler methods add_reference() and 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 and changes:

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:

Synchronization Classes Reorganized

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.

ACE_Bound_Ptr::get() Now const

The ACE_Bound_Ptr::get() method is now declared const.

ACE_Refcounted_Auto_Ptr::get() Now const

The ACE_Refcounted_Auto_Ptr::get() method (and the associated ACE_Refcounted_Auto_Ptr_Rep::get() method) are now declared const.

ACE_Notification_Strategy::mask() Now const

The ACE_Notification_Strategy::mask() method is now declared const.

Alignment in ACE Memory Allocators

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 in ace/Malloc_T.h.

ACE_New_Allocator Methods Un-inlined

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 Refuses to Register Signal Handler

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. Thanks to Carsten Prescher for pointing this out this inconsistency.

ACE_Log_Record::print() Signature Change

The 3rd argument to ACE_Log_Record::print() was changed from ostream to ACE_OSTREAM_TYPE.

Timeprobes

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.

Metrics Cache

Added a new Metrics Cache. No further information on this was provided by the author. Please see ace/Metrics_Cache* for details.

Applications' Versioned Shared Libraries

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.

ACE_Process Copy Constructor and Assignment Operator

The ACE_Process copy constructor and assignment operator methods were moved to the private part of the class to disallow copying.

Easier to Use ACE Makefile Scheme

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 deal.

Ability to Change the ACE Logging Timestamp

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.

XTI Versus TLI

Previous ACE versions favored use of TLI over XTI when both were available. This has been reversed; XTI is now favored.

Known Problems With Version 5.4

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.

Failure Unpacking Kit in Windows

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.

Compile Errors for Windows CE/Pocket PC

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.

Compile Errors on HP-UX With g++

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.

Template-related Link Errors on AIX

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.

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 or Crashes 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.

Priority_Task_Test Fails on Red Hat Linux 9 and Enterprise Linux 3

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.

About this document ...

ACE Version 5.4 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 ace54.tex

The translation was initiated by Steve Huston on 2004-02-25


Steve Huston 2004-02-25