Categories: Symbian OS | Code Examples | Symbian C++ | How To

This page was last modified 17:29, 1 July 2008.

From Forum Nokia Wiki

DLL can manage writable static data on a per-thread basis using thread-local storage, commonly known as ”TLS”. This allocates a single machine word of writable static data per thread for every DLL, regardless of whether the DLL uses it. Obviously, the memory overhead is far less significant than allocating a 4 KB chunk for each DLL which uses static data. However, the price of using TLS instead of Direct Memory Access is performance; data is retrieved from TLS about 30 times slower than direct access, because the lookup involves a context switch to the kernel in order to access the data.

Thread-local storage is usually initialized when the DLL is attached to a thread within the DLL entry point, E32Dll().Typically, code is added to construct the struct containing the global data and store it in thread-local storage using the static function Dll::SetTLS().To access the data, you should use the static function Dll::Tls(). This will return a TAny* which can be cast and used to access the data. For simplicity, you may wish to provide a utility function, or set of functions, to access the data from a single point.

TLS is thread and DLL -specific so every DLL in a thread can use it without risk of mixups.

Usage example

// Create an object and store the pointer in TLS
CSomeClass* object = CSomeClass::NewL();
User::LeaveIfError( Dll::SetTls( object ) );
 
// Get the object from TLS
object = static_cast<CSomeClass*>( Dll::Tls() );
 
// When done with the object, delete it and free TLS
delete object;
object = NULL;
Dll::FreeTls();

Usage example in an EXE project

The above code uses the static Dll class to access the TLS which means it only works in a DLL project. TLS can also be used in an EXE project, but through a different static class. UserSvr provides the same API to TLS except that it requires somekind of an id to the pointer being stored. The Dll class actually uses UserSvr to access TLS provinding the DLL module handle as the id. The same code example in an EXE project would look something like this:

#include <e32svr.h> // For UserSvr
 
// Define a handle. This has to be unique within the thread. 
const TInt KMyTlsHandle = 0xC0FFEE;
 
// Create an object and store the pointer in TLS
CSomeObject* object = CSomeObject::NewL();
User::LeaveIfError( UserSvr::DllSetTls( KMyTlsHandle, object ) );
 
// Get the object from TLS
object = static_cast<CSomeObject*>( UserSvr::DllTls( KMyTlsHandle ) );
 
// When done with the object, delete it and free TLS
delete object;
object = NULL;
UserSvr::DllFreeTls( KMyTlsHandle );