Welcome to the October 2004 edition of Riverace's ACE News and Tips newsletter. This issue contains an explanation of ACE's initialization and shutdown (a perennial FAQ), news about what's coming up in the next ACE release, and a note about our redesigned web site.

Please forward this newsletter to anyone you think may be interested! Anyone who wishes to receive their own copy of this newsletter can subscribe at http://www.riverace.com/subscribe2/index.mv. If you no longer wish to subscribe, removal directions are at the bottom of this page.

Please reply with any feedback you have on this newsletter, as well as ideas for information you'd like to see in upcoming newsletters. We want to be as helpful as possible, so please let us know how we can do that.

ACE Tip: Proper ACE Initialization and Shutdown

Every once in a while, someone brings working ACE code into a new environment (most often Windows), rebuilds it, and expects it to run as well in the new environment as in the old. A very reasonable expectation given ACE's excellent cross-platform portability and long history of "write once, build anywhere" reliability. Then it crashes shortly after startup, deep within the innards of ACE, in code that users almost never need look at. These crashes are nearly always a result of ACE not being initialized correctly.

More in-depth discussion of the issues surrounding initialization are given in APG section 1.6.3. This article contains a summary of the issues and an explanation of how to properly initialize ACE.

Why the Big Fuss?

Why should there even be an issue with initialization? You can use static objects, right? Not safely, no. The C++ standard doesn't define all behaviors applicable to run-time behavior, order of initialization, etc., of static objects. Also, there's no standardized behavior of statics in the presence of multiple threads. To provide correct behavior across all platforms, ACE offers a safe way to use singleton objects (singletons are explained more in APG and C++NPv2). The management of singletons is handled internally by the ACE_Object_Manager, and even if your code doesn't use singletons, ACE uses them internally so the object manager needs to be set up properly. This is where the proper initialization of ACE comes into play. Pieces of ACE will internally access the object manager to instantiate and access singletons. If this happens without the object manager being initialized, the program will crash.

The Buck (err, initialization) Stops Here

Statics are not universally safe to use for initializing, so ACE implements an object manager. But how does the object manager get initialized? There are three ways:

1. It's a static object. What?! Some platforms do handle static object initialization and shutdown correctly, even inside a shared library. Also, when the object manager is initialized, ACE hasn't spawned any threads, so the environment is fairly safe. On platforms that provide this capability, the ACE object manager is, indeed, a static object. Most UNIXes fall into this category, which is why the initialization issue almost never crops up there.
2. It's created on the main program's run-time stack. When ACE's OS-layer header files are included (in ACE 5.4 and later, ace/OS_main.h handles this) the main() entrypoint in your program is substituted with a main() that locally creates an ACE_Object_Manager instance then calls your program's main entrypoint. When your program returns out of the main entrypoint, the object manager goes out of scope and properly cleans up any singletons your program created, as well as ACE's internals. This is why your program should never call exit() or any other system call that aborts the normal shutdown sequence---it skips ACE's shutdown procedure. This is the initialization method used primarily on Windows.
3. The program explicitly initializes and shuts down ACE. If the platform doesn't handle static creation and shutdown safely, and the program can't make use of the redefined main() entrypoint, the program must explicitly initialize and shut down ACE. To initialize ACE, the following method must be called:

   ACE::init();

   This must be called before any other ACE methods are invoked. When the program is ready to shut down, the following method must be called after all ACE work is complete:

   ACE::fini();

   It is not safe to invoke any ACE methods after ACE::fini() is called. The calls to ACE::init() are reference-counted, so the application must call ACE::fini() the same number of times as ACE::init() before shutdown actually occurs.

The reason that initialization issues often crop up in Windows programs is that a mock-up prototype is done as a console program (with a main() entrypoint) then converted to a regular Windows program (without a main() entrypoint). Since Windows can't reliably use method 1 above, and the main() entrypoint is removed, ACE is not initialized unless an explicit ACE::init() call is added.

Also note that when designing a library (DLL) that uses ACE, but the programs that'll use this new library don't use ACE, the library must be careful to initialize ACE without the user program's intervention (or use of the redefined main() entrypoint in method 2, above). In these cases, it is recommended that a specific entrypoint is added to the new library for initialization (and one for shutdown). These entrypoints should call ACE::init() and ACE::fini(), respectively. In case you're thinking of using the Windows' DllMain entrypoint for this, it's a good thought, but not reliable. We've tried it. It's much better to add initialize/shutdown entrypoints to your library and require programs to call them.

If you have more questions about ACE initialization and shutdown, please feel free to file a support request to get further clarification and information. If you're not a Riverace support customer, you can learn more about our support services at http://www.riverace.com/support.htm.

ACE.next: What's New?

The ACE development community is hard at work on the next version of ACE. Here are some of the things you can look forward to (items in bold are new or changed since last month):

• Native library path-searching. Previous ACE versions's implementation of ACE_DLL (used in loading dynamic services) implemented a search of the configured path-search to try and locate the desired library file (DLL) and then used the full pathname to load the library. This skirted some platforms's rules for path search and security settings. This has been changed in the next ACE version to make use of all of the native platform's path-search and security facilities.
• Improved wide-character support. Wide-character support has been included in ACE for many years on Windows (also known as Unicode builds). However, wide-character support for POSIX platforms has been sorely lacking. As ACE's reach expands, this has become a more important issue. Riverace is leading the completion of wide-character support in the next version of ACE. This support is also being included in the ACE 5.4b fix kit, which will be available by mid October (we've held it back to get more of the example programs building correctly with wide-character usage).
• GNU autotools support. Riverace is the lead developer in charge of adding auto-configure support to ACE. For native-build, non-Windows systems, autoconf will very likely become the way to configure and build ACE. This will help insure that ACE uses the latest features available on each supported platform, and reduce the work required to build ACE. No more picking the right config.h or platform_macros.GNU file. Just do ./configure then make. Ahhh...
• New compiler support. Support for g++ 3.4 and Microsoft Visual C++ 2005 are being added.
• Newer C++ Features Being Used. As the range of ACE-supported compilers matures and older compilers are taken out of service, ACE can make more use of newer C++ features while still maintaining its stellar portability record. For example, many methods that returned 1 or 0 as an int now return bool. Small steps, yes, but significant ones. You'll see more modern C++ usage as time goes on.

New Web Site: www.riverace.com Relaunched

The Riverace Corporation web site (http://www.riverace.com/) has been redesigned and redeployed. The goals were to make the site easier to navigate and make it easier to find what you need quickly. Since most site visitors are looking for either ACE kits or documentation, there are direct links to those sections of the site right on the top banner of each page. There are also expanded sections for the ACE books including supplemental information such as errata and sample chapters. We're also filling out the platform-specific pages to give more helpful information on tools and tips for using ACE across the platforms the Riverace supports.

If you have any feedback on the site, or ideas on what could be done to further improve its usefulness, please send email to shuston@riverace.com with your ideas.

New Project Coming Up?

If you're planning a new project to start soon, or find yourself grappling with how to apply ACE to your current project, remember that Riverace provides world-class development and consulting services with special expertise in ACE. We can help you be sure that your new system is designed to take full advantage of ACE's power and flexibility, getting your system delivered in the shortest possible time and with the highest level of quality. Please contact Steve Huston at 508-541-9180 to discuss how Riverace can help you.

Useful ACE Information

• Riverace-supported ACE Releases (don't forget, ACE Annual Support customers get no-charge access to all Fix Kits!)

• ACE Books are available via riverace.com from amazon.com
• Looking for ACE reference documentation? Please see www.riverace.com/docs.htm
• Need more help? Riverace is the premier support provider for ACE. We also offer hands-on design and consulting services to help you get the most out of ACE's power and flexibility.

Quotables

"I also wanted to take this opportunity to express my appreciation for the quality and responsiveness of your organization.  It is a very rare pleasure to work with an organization that provides in-depth technical support while remaining strongly customer focused - a fact you clearly demonstrate on every interaction.  With your help, we have been able to dramatically improve our development schedule while reducing the overall cost and resources required.  Riverace has exceeded our expectations without exception."

Christopher W. Midgley
Chief Technology Officer
LiveVault Corporation

This Newsletter...

... is produced by Riverace Corporation to educate the ACE user community about ACE and available ACE resources, give tips on how to use ACE more effectively, and explain how Riverace can help you make the most of this powerful toolkit.

About Us

Riverace Corporation is the premier support service provider for the ACE toolkit worldwide. Steve Huston, Riverace's President/CEO and founder, has over 20 years' experience developing network protocols and applications. He has coauthored three books on ACE's design and usage and is considered an expert by ACE users around the world. Riverace has been focused on providing world-class technical support and consulting services for ACE since 1997.