Language

The Free and Open Productivity Suite
Released: Apache OpenOffice 4.1.15

API

SDK

Tips ‘n’ Tricks

Miscellaneous

 Overview   Namespace   Class   Index   Help 

Global Functions in Global Namespace C++
in Sourcefile unload.h

rtl_addUnloadingListener
extern "C"
sal_Int32 rtl_addUnloadingListener(
rtl_unloadingListenerFunc callback,
void * _this );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Description
The function registered an unloading listener. The callback argument is a function which is called when the unloading procedure has been initiated by a call to rtl_unloadUnusedLibraries. The second argument is used to distinguish between different listener instances and may be NULL. It will be passed as argument when the callback function is being called. The return value identifies the registered listener and will be used for removing the listener later on. If the same listener is added more then once then every registration is treated as if made for a different listener. That is, a different cookie is returned and the callback function will be called as many times as it has been registered.
Parameters
callback 
- a function that is called to notify listeners.
this 
- a value to distinguish different listener instances
Return
identifier which is used in rtl_removeUnloadingListener
rtl_moduleCount_acquire
extern "C"
void rtl_moduleCount_acquire(
rtl_ModuleCount * that );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Default implementation for rtl_ModuleCount.acquire. Use this function along with rtl_StandardModuleCount.
rtl_moduleCount_canUnload
extern "C"
sal_Bool rtl_moduleCount_canUnload(
rtl_StandardModuleCount * that,
TimeValue * libUnused );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Default implementation for component_canUnload. Use this function along with rtl_StandardModuleCount.
rtl_moduleCount_release
extern "C"
void rtl_moduleCount_release(
rtl_ModuleCount * that );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Description
Default implementation for rtl_ModuleCount.release. Use this function along with rtl_StandardModuleCount.
rtl_registerModuleForUnloading
extern "C"
sal_Bool rtl_registerModuleForUnloading(
oslModule module );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
By registering a module, one declares that a module supports the unloading mechanism. One registers a module by calling this function.

Description
A module can only be unloaded from memory when it has been registered as many times as it has been loaded. The reason is that a library can be "loaded" several times by osl_loadModule within the same process. The function will then return the same module handle because the library will effectively only be loaded once. To remove the library from memory it is necessary to call osl_unloadModule as often as osl_loadModule was called. The function rtl_unloadUnusedModules calls osl_unloadModule for a module as many times as it was registered. If, for example, a module has been registered one time less then osl_loadModule has been called and the module can be unloaded then it needs a call to rtl_unloadUnusedModules and an explicit call to osl_unloadModule to remove the module from memory.

A module must be registered every time it has been loaded otherwise the unloading mechanism is not effective.

Before a module is registered, one has to make sure that the module is in a state that prevents it from being unloaded. In other words, component_canUnload must return sal_False. Assuming that component_canUnload returns sal_True and it is registered regardless, then a call to rtl_unloadUnusedModules causes the module to be unloaded. This unloading can be set off by a different thread and the thread which registered the module is "unaware" of this. Then when the first thread tries to obtain a factory or calls another function in the module, the application will crash, because the module has been unloaded before. Therefore one has to ensure that the module cannot be unloaded before it is registered. This is simply done by obtaining a factory from the module. As long as a factory or some other object, which has been created by the factory, is alive, the component_canUnload function will return sal_False.

Loading and registering have to be in this order:

  • load a library (osl_loadModule)
  • get the component_getFactory function and get a factory
  • register the module (rtl_registerModuleForUnloading
Usually the service manager is used to obtain an instance of a service. The service manager registers all modules which support the unloading mechanism. When the service manager is used to get service instances than one does not have to bother about registering.
Parameters
module 
a module handle as is obtained by osl_loadModule
Return
sal_True - the module could be registered for unloading, sal_False otherwise
rtl_removeUnloadingListener
extern "C"
void rtl_removeUnloadingListener(
sal_Int32 cookie );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Description
Listeners (the callback functions) must be unregistered before the listener code becomes invalid. That is, if a module contains listener code, namely callback functions of type rtl_unloadingListenerFunc, then those functions must not be registered when component_canUnload returns sal_True.
Parameters
cookie 
is an identifier as returned by rtl_addUnloadingListener function.
rtl_unloadUnusedModules
extern "C"
void rtl_unloadUnusedModules(
TimeValue * libUnused );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Description
This function sets off the unloading mechanism. At first it notifies the unloading listeners in order to give them a chance to do cleanup and get their threads in a safe state. Then all registered modules are asked if they can be unloaded. That is, the function calls component_canUnload on every registered module. If sal_True is returned then osl_unloadModule is called for the belonging module as often as it is registered.

A call to osl_unloadModule does not guarantee that the module is unloaded even if its component_canUnload function returns sal_True.

The optional in-parameter libUnused specifies a period of time which a library must be unused in order to qualify for being unloaded. By using this argument one can counter the multithreading problem as described further above. It is in the responsibility of the user of this function to provide a timespan big enough to ensure that all threads are out of modules (see component_canUnload).

The service managers which have been created by functions such as createRegistryServiceFactory (declared in cppuhelper/servicefactory.hxx) are registered listeners and release the references to factories on notification.

Parameters
libUnused 
span of time that a module must be unused to be unloaded. the 
argument is optional.
rtl_unregisterModuleForUnloading
extern "C"
void rtl_unregisterModuleForUnloading(
oslModule module );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Description
The function revokes the registration of a module. By calling the function for a previously registered module one prevents the module from being unloaded by this unloading mechanism. However, in order to completely unregister the module it is necessary to call the function as often as the module has been registered.

rtl_unloadUnusedModules unregisters the modules which it unloads. Therefore there is no need to call this function unless one means to prevent the unloading of a module.

Parameters
module 
a module handle as is obtained by osl_loadModule
Top of Page

Copyright © 2012, The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache, the Apache feather logo, Apache OpenOffice and OpenOffice.org are trademarks of The Apache Software Foundation. Other names may be trademarks of their respective owners.

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache, OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. The Apache feather logo is a trademark of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.