--- name: "ACE_Object_Manager" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_Object_Manager" --- # ACE\_Object\_Manager(3) Manager for ACE library services and singleton cleanup. ## NAME ACE\_Object\_Manager - Manager for ACE library services and singleton cleanup. ## SYNOPSIS ``` #include class ACE_Object_Manager : public ACE_Object_Manager_Base { public: virtual int init (void); virtual int fini (void); static int starting_up (void); static int shutting_down (void); static int at_exit (ACE_Cleanup *object, void *param = 0); static int at_exit ( void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param ); static int at_thread_exit ( void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param ); enum Preallocated_Object{ ACE_FILECACHE_LOCK, #if defined ( ACE_HAS_THREADS) ACE_STATIC_OBJECT_LOCK, #endif #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) ACE_MT_CORBA_HANDLER_LOCK, ACE_DUMP_LOCK, ACE_SIG_HANDLER_LOCK, ACE_SINGLETON_NULL_LOCK, ACE_SINGLETON_RECURSIVE_THREAD_LOCK, ACE_THREAD_EXIT_LOCK, #if !defined (ACE_LACKS_ACE_TOKEN) ACE_TOKEN_MANAGER_CREATION_LOCK, ACE_TOKEN_INVARIANTS_CREATION_LOCK, #endif ACE_PROACTOR_EVENT_LOOP_LOCK, #endif ACE_APPLICATION_PREALLOCATED_OBJECT_DECLARATIONS ACE_PREALLOCATED_OBJECTS }; enum Preallocated_Array{ ACE_EMPTY_PREALLOCATED_ARRAY, ACE_APPLICATION_PREALLOCATED_ARRAY_DECLARATIONS ACE_PREALLOCATED_ARRAYS }; static ACE_Sig_Set &default_mask (void); static int get_singleton_lock (ACE_Null_Mutex *&); static int get_singleton_lock (ACE_Thread_Mutex *&); static int get_singleton_lock (ACE_Mutex *&); static int get_singleton_lock (ACE_Recursive_Thread_Mutex *&); static int get_singleton_lock (ACE_RW_Thread_Mutex *&); static ACE_Object_Manager *instance (void); static void *preallocated_object[ACE_PREALLOCATED_OBJECTS]; static void *preallocated_array[ACE_PREALLOCATED_ARRAYS]; ACE_Object_Manager (void); ~ACE_Object_Manager (void); private: ACE_OS_Exit_Info exit_info_; ACE_Object_Manager_Preallocations *preallocations_; ACE_Sig_Adapter *ace_service_config_sig_handler_; int at_exit_i ( void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param ); static ACE_Object_Manager *instance_; ACE_Recursive_Thread_Mutex *internal_lock_; ACE_Cleanup_Adapter *singleton_null_lock_; ACE_Cleanup_Adapter *singleton_recursive_lock_; void *ts_storage_[ACE_TSS_Emulation::ACE_TSS_THREAD_KEYS_MAX]; friend class ACE_Object_Manager_Manager; ACE_Object_Manager (const ACE_Object_Manager &); ACE_Object_Manager &operator= (const ACE_Object_Manager &); }; ``` ## DESCRIPTION The ACE\_Object\_Manager manages cleanup of objects, typically singletons, at program termination. In addition to managing the cleanup of the ACE library, it provides an interface for application to register objects to be cleaned up. This class also shuts down ACE library services, so that they can reclaim their storage, at program termination. It works by creating a static instance whose destructor gets called along with those of all other static objects. Hooks are provided for application code to register objects and arrays for cleanup, e.g., destruction. The order of such cleanup calls is in the reverse order of registration, i.e., that last object/array to register gets cleaned up first. The ACE\_Object\_Manager API includes ACE\_Managed\_Object. That class is contained in a separate file because it is a template class, and some compilers require that template and non-template class definitions appear in separate files. Please see ace/Managed\_Object.h for a description of that part of the API. In summary, ACE\_Managed\_Object provides two adapters, the ACE\_Cleanup\_Adapter and ACE\_Managed\_Object template classes for adapting objects of any type to be easily managed by the ACE\_Object\_Manager. There are several mechanisms for adapting objects and arrays for cleanup at program termination, in roughly increasing order of ease-of-use: 1\) Derive the object's class from ACE\_Cleanup. 2) Allow the ACE\_Object\_Manager to both dynamically allocate\ and deallocate the object. 3) Provide an ACE\_CLEANUP\_FUNC cleanup hook for the object or\ array. 4) Allow the ACE\_Object\_Manager to both preallocate the object\ or array, either statically in global data or dynamically on\ the heap, when its singleton instance is construction. There are also several mechanisms for registering objects and arrays for cleanup. In decreasing order of flexibility and complexity (with the exception of the last mechanism): 1\) ACE\_Object\_Manager::at\_exit (void \*object,\ ACE\_CLEANUP\_FUNC cleanup\_hook,\ void \*param);\ can be used to register any object or array for any\ cleanup activity at program termination. 2\) ACE\_Object\_Manager::at\_exit (ACE\_Cleanup \*object,\ void \*param = 0);\ can be used to register an ACE\_Cleanup object\ for any cleanup activity at program termination. The final mechanism is not general purpose, but can only\ be used to allocate objects and arrays at program startup: 3\) ACE\_Managed\_Object::get\_preallocated\_object\ (ACE\_Object\_Manager::Preallocated\_Object id);\ and\ ACE\_Managed\_Object::get\_preallocated\_array\ (ACE\_Object\_Manager::Preallocated\_Array id);\ can only be used to allocate objects at program startup,\ either in global data or on the heap (selected at compile\ time). These are intended to replace static locks, etc. Instead of creating a static ACE\_Object\_Manager instance, one can alternatively be created on the stack of the main program thread. It is created just after entry to ::main (int, char \*\[\]), and before any existing code in that function is executed. To enable this alternative, add #define ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER before including the platform specific config-\* file in ace/config.h prior to building the ACE library and your applications. This #define is enabled in some config files that are supplied with ACE. To ensure a static object manager is used, #undef ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER \*after\* including the platform specific config-\* file. Note that the ACE\_Object\_Manager \_must\_ be created before any threads are spawned by the program. If ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER is not #defined, the ACE library creates a static, singleton ACE\_Object\_Manager instance. The instance is placed in global program data, and constructed via a static object constructor. If ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER is #defined, the ACE\_Object\_Manager instance is created on the stack of the main program thread, as noted above. With ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER enabled, the ACE library has no static objects that require destruction. However, there are two drawbacks to using it: 1\) main (int, char \*\[\]) must be declared with arguments, even\ if they're not used. All of ACE is converted to this, so\ just applications have to be concerned with it. 2\) If there any static objects that depend on those that are\ cleaned up by the Object\_Manager, they'll get cleaned up too\ late. The ACE tests do not violate this requirement.\ However, applications may have trouble with it. NOTE on the use of ::exit -- ::exit does not destroy static objects. Therefore, if ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER is enabled, the ACE\_Object\_Manager instance will \*not\* be destroyed if ::exit is called! However, ACE\_OS::exit will properly destroy the ACE\_Object\_Manager. It is highly recommended that ACE\_OS::exit be used instead of ::exit. However, ::exit and ACE\_OS::exit are tricky to use properly, especially in multithread programs. It is much safer to throw an exception (or simulate that effect) that will be caught by main instead of calling exit. Then, main can perform any necessary application-specific cleanup and return the status value. In addition, it's usually best to avoid calling ::exit and ACE\_OS::exit from threads other than the main thread. Thanks to Jeff Greif jmg@trivida.com for pointing out that ::exit doesn't destroy automatic objects, and for developing the recommendations in this paragraph. Instead of creating a static ACE\_Object\_Manager, or letting ACE create it on the stack of main for you, another alternative is to #define ACE\_DOESNT\_INSTANTIATE\_NONSTATIC\_OBJECT\_MANAGER. With that #define, the application must create the ACE\_Object\_Manager. The recommended way is to call ACE::init at the start of the program, and call ACE::fini at the end. Alternatively, the application could explicity construct an ACE\_Object\_Manager. ## PUBLIC MEMBERS ``` virtual int init (void); ``` Explicitly initialize (construct the singleton instance of) the ACE\_Object\_Manager. Returns 0 on success, -1 on failure, and 1 if it had already been called. ``` virtual int fini (void); ``` Explicitly destroy the singleton instance of the ACE\_Object\_Manager. Returns 0 on success, -1 on failure, and 1 if it had already been called. ``` static int starting_up (void); ``` Returns 1 before the ACE\_Object\_Manager has been constructed. This flag can be used to determine if the program is constructing static objects. If no static object spawns any threads, the program will be single-threaded when this flag returns 1. (Note that the program still might construct some static objects when this flag returns 0, if ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER is not defined.) ``` static int shutting_down (void); ``` Returns 1 after the ACE\_Object\_Manager has been destroyed. This flag can be used to determine if the program is in the midst of destroying static objects. (Note that the program might destroy some static objects before this flag can return 1, if ACE\_HAS\_NONSTATIC\_OBJECT\_MANAGER is not defined.) ``` static int at_exit (ACE_Cleanup *object, void *param = 0); ``` Register an ACE\_Cleanup object for cleanup at process termination. The object is deleted via the ace\_cleanup\_destroyer. If you need more flexiblity, see the other at\_exit method below. For OS's that do not have processes, cleanup takes place at the end of main. Returns 0 on success. On failure, returns -1 and sets errno to: EAGAIN if shutting down, ENOMEM if insufficient virtual memory, or EEXIST if the object (or array) had already been registered. ``` static int at_exit ( void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param ); ``` Register an object (or array) for cleanup at process termination. "cleanup\_hook" points to a (global, or static member) function that is called for the object or array when it to be destroyed. It may perform any necessary cleanup specific for that object or its class. "param" is passed as the second parameter to the "cleanup\_hook" function; the first parameter is the object (or array) to be destroyed. "cleanup\_hook", for example, may delete the object (or array). For OS's that do not have processes, this function is the same as at\_thread\_exit. Returns 0 on success. On failure, returns -1 and sets errno to: EAGAIN if shutting down, ENOMEM if insufficient virtual memory, or EEXIST if the object (or array) had already been registered. ``` static int at_thread_exit ( void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param ); ``` Similar to at\_exit, except that the cleanup\_hook is called when the current thread exits instead of when the program terminates. ``` static ACE_Sig_Set &default_mask (void); ``` Accesses a default signal set used, for example, in ACE\_Sig\_Guard methods. Deprecated: use ACE\_Object\_Manager::default\_mask () instead. ``` static int get_singleton_lock (ACE_Null_Mutex *&); ``` Accesses an ACE\_Null\_Mutex to be used for construction of ACE\_Singletons. Returns 0, and the lock in the argument, on success; returns -1 on failure. ``` static int get_singleton_lock (ACE_Thread_Mutex *&); ``` Accesses a non-recursive ACE\_Thread\_Mutex to be used for construction of ACE\_Singletons. Returns 0, and the lock in the argument, on success; returns -1 on failure. ``` static int get_singleton_lock (ACE_Mutex *&); ``` Accesses a non-recursive ACE\_Mutex to be used for construction of ACE\_Singletons. Returns 0, and the lock in the argument, on success; returns -1 on failure. ``` static int get_singleton_lock (ACE_Recursive_Thread_Mutex *&); ``` Accesses a recursive ACE\_Recursive\_Thread\_Mutex to be used for construction of ACE\_Singletons. Returns 0, and the lock in the argument, on success; returns -1 on failure. ``` static int get_singleton_lock (ACE_RW_Thread_Mutex *&); ``` Accesses a readers/writer ACE\_RW\_Thread\_Mutex to be used for construction of ACE\_Singletons. Returns 0, and the lock in the argument, on success; returns -1 on failure. ``` static ACE_Object_Manager *instance (void); ``` Accessor to singleton instance. Because static member functions are provided in the interface, this should not be public. However, it is public so that ACE\_Managed\_ObjectTYPE can access it. ``` static void *preallocated_object[ACE_PREALLOCATED_OBJECTS]; ``` Table of preallocated objects. ``` static void *preallocated_array[ACE_PREALLOCATED_ARRAYS]; ``` Table of preallocated arrays. ``` ACE_Object_Manager (void); ``` ``` ~ACE_Object_Manager (void); ``` ## PRIVATE MEMBERS ``` ACE_OS_Exit_Info exit_info_; ``` For at\_exit support. ``` ACE_Object_Manager_Preallocations *preallocations_; ``` Preallocated objects collection. ``` ACE_Sig_Adapter *ace_service_config_sig_handler_; ``` ACE\_Service\_Config signal handler. ``` int at_exit_i ( void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param ); ``` Register an object or array for deletion at program termination. See description of static version above for return values. ``` static ACE_Object_Manager *instance_; ``` Singleton pointer. ``` ACE_Recursive_Thread_Mutex *internal_lock_; ``` Lock that is used to guard internal structures. ``` ACE_Cleanup_Adapter *singleton_null_lock_; ``` Null lock for guarding singleton creation. ``` ACE_Cleanup_Adapter *singleton_recursive_lock_; ``` Lock for guarding singleton creation, when Object\_Manager hasn't been started up, or has already been shut down. ``` void *ts_storage_[ACE_TSS_Emulation::ACE_TSS_THREAD_KEYS_MAX]; ``` ``` friend class ACE_Object_Manager_Manager; ``` ``` ACE_Object_Manager (const ACE_Object_Manager &); ``` ``` ACE_Object_Manager &operator= (const ACE_Object_Manager &); ``` ## AUTHORS David L. Levine, Matthias Kerkhoff, and Per Andersson ## LIBRARY ace