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 );
- extern "C"
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 beNULL
. 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 );
- extern "C"
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 withrtl_StandardModuleCount
.
- rtl_moduleCount_canUnload
- extern "C"
sal_Bool rtl_moduleCount_canUnload( rtl_StandardModuleCount * that, TimeValue * libUnused );
- extern "C"
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 withrtl_StandardModuleCount
.
- rtl_moduleCount_release
- extern "C"
void rtl_moduleCount_release( rtl_ModuleCount * that );
- extern "C"
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 withrtl_StandardModuleCount
.
- rtl_registerModuleForUnloading
-
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 callosl_unloadModule
as often asosl_loadModule
was called. The functionrtl_unloadUnusedModules
callsosl_unloadModule
for a module as many times as it was registered. If, for example, a module has been registered one time less thenosl_loadModule
has been called and the module can be unloaded then it needs a call tortl_unloadUnusedModules
and an explicit call toosl_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 returnsal_False
. Assuming thatcomponent_canUnload
returnssal_True
and it is registered regardless, then a call tortl_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, thecomponent_canUnload
function will returnsal_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
- load a library (
- 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 );
- extern "C"
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 whencomponent_canUnload
returnssal_True
. - Parameters
cookie is an identifier as returned by
rtl_addUnloadingListener
function.
- rtl_unloadUnusedModules
- extern "C"
void rtl_unloadUnusedModules( TimeValue * libUnused );
- extern "C"
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 thenosl_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 itscomponent_canUnload
function returnssal_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 (seecomponent_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 );
- extern "C"
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.