Global Functions in Namespace in Sourcefile unload.h

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

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

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

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