Open Inventor Release 2024.1.3
 
Loading...
Searching...
No Matches
SbThreadLocalStorage Class Reference

VSG extension Thread Local Storage (TLS) class. More...

#include <Inventor/threads/SbThreadLocalStorage.h>

Public Types

typedef void SoInitTLSClassCB()
 
typedef void SoExitTLSClassCB()
 

Static Public Member Functions

static void createStorage (size_t &classThreadId, const size_t byteSize, SoInitTLSClassCB *initFunc=NULL, SoExitTLSClassCB *exitFunc=NULL, const char *funcName=NULL)
 Creates or updates the local storage for the current thread.
 
static void deleteStorage (size_t &classThreadId, const char *funcName=NULL)
 Deletes the local storage for all threads.
 
static bool isInitialized (const size_t classThreadId)
 Returns true if a TLS storage has already been allocated for the given classThreadId.
 
static void * getStorage (const size_t classThreadId)
 Returns a pointer on the storage for the given classThreadId.
 

Related Symbols

(Note that these are not member symbols.)

#define SB_THREAD_INIT_CLASS(_className_, _structName_)    SbThreadLocalStorage::createStorage(_className_::MT_Id, sizeof(struct _className_::_structName_), _className_::initTLSClass, _className_::exitTLSClass, OIV_FUNCTION );
 Requests allocation of thread local storage.
 
#define SB_THREAD_IS_INITIALIZED(_className_)    SbThreadLocalStorage::isInitialized(_className_::MT_Id)
 Returns true if a TLS storage has been allocated for the given classThreadId.
 
#define SB_THREAD_EXIT_CLASS(_className_)    SbThreadLocalStorage::deleteStorage( _className_::MT_Id, OIV_FUNCTION );
 Requests deallocation of thread local storage.
 
#define GET_THREAD_LOCAL_VAR(_className_, _structName_, _varName_)    ((static_cast<struct _className_::_structName_ *> (SbThreadLocalStorage::getStorage(_className_::MT_Id)))->_varName_)
 Gets direct access to current thread storage inside variable.
 
#define GET_THREAD_LOCAL_STORAGE(_className_)    (static_cast<void *> (SbThreadLocalStorage::getStorage(_className_::MT_Id)))
 Returns pointer to current thread storage for defined class.
 
#define SB_THREAD_TLS_HEADER()
 Defines headers for required member variables in thread storage management.
 
#define SB_THREAD_TLS_SOURCE(_className_)
 Defines source for required member variables in thread storage management.
 
#define SoNodeTLS   SbThreadLocalStorage
 Compatiblity define SoNodeTLS to SbThreadLocalStorage.
 

Detailed Description

VSG extension Thread Local Storage (TLS) class.

This class allows to create thread local data storage. This allow to manage per thread static global variables in multithread mode.

Example on how to use the Thread Local Storage (TLS):

In this example we move static variables s_myStaticVar1 and s_myStaticVar2 of the class MyClass to Thread Local Storage,

  • Original myClass implementation :
    class myClass
    {
    static void initClass();
    static void exitClass();
    ...
    static int s_myStaticVar1;
    static float* s_myStaticVar2;
    ...
    }
    void myClass::initClass()
    {
    s_myStaticVar1 = 32;
    s_myStaticVar2 = new float[32];
    }
    void myClass::exitClass()
    {
    s_myStaticVar1 = 0;
    delete [] s_myStaticVar2;
    }
  • Modified myClass implementation to support use TLS :
    class myClass
    {
    static void initClass();
    static void exitClass();
    // Declare necessary members and methods for TLS usage
    SB_THREAD_TLS_HEADER();
    ...
    // structure to handle per thread static variables
    struct MTstruct {
    int s_myStaticVar1;
    float* s_myStaticVar2;
    }
    ...
    }
    // Properly initilize members and methods for TLS usage
    void myClass::initClass()
    {
    // register and reserve space for TLS
    SB_THREAD_INIT_CLASS(myClass, MTstruct);
    }
    void myClass::exitClass()
    {
    }
    void myClass::initTLSClass()
    {
    // get access to TLS and init/allocate variables once per thread
    struct myClass::MTstruct * mtstruct = (struct myClass::MTstruct *)GET_THREAD_LOCAL_STORAGE(myClass) ;
    mtstruct->s_myStaticVar1 = 32;
    mtstruct->s_myStaticVar2 = new float[32];
    }
    void myClass::exitTLSClass()
    {
    if (SbThreadLocaStorage::isInitialized(myClass::MT_id))
    {
    // get access to TLS and deallocate variables once per thread
    struct myClass::MTstruct * mtstruct = (struct myClass::MTstruct *)GET_THREAD_LOCAL_STORAGE(myClass) ;
    delete [] mtstruct->s_myStaticVar2;
    }
    }
    #define GET_THREAD_LOCAL_STORAGE(_className_)
    Returns pointer to current thread storage for defined class.
    #define SB_THREAD_INIT_CLASS(_className_, _structName_)
    Requests allocation of thread local storage.
    #define SB_THREAD_TLS_SOURCE(_className_)
    Defines source for required member variables in thread storage management.
  • Each time a variable in Thread Local Storage is used, the structure containing this variable needs to be fetched using the following macro :
    struct myClass::MTstruct * mtstruct = (struct myClass::MTstruct *) GET_THREAD_LOCAL_STORAGE(myClass) ;
    The variables can then be used as, for example: mtstruct->variable1.
    Another macro exists to bring back one single variable of the structure :
    GET_THREAD_LOCAL_VAR(myClass, MTstruct, variable1)
    #define GET_THREAD_LOCAL_VAR(_className_, _structName_, _varName_)
    Gets direct access to current thread storage inside variable.

SEE ALSO

SbThread, SbThreadAutoLock, SbThreadAutoReadLock, SbThreadAutoWriteLock, SbThreadBarrier, SbThreadRWMutex, SbThreadSignal

Definition at line 234 of file SbThreadLocalStorage.h.

Member Typedef Documentation

◆ SoExitTLSClassCB

typedef void SoExitTLSClassCB()

Definition at line 33 of file SbThreadLocalStorage.h.

◆ SoInitTLSClassCB

typedef void SoInitTLSClassCB()

Definition at line 31 of file SbThreadLocalStorage.h.

Member Function Documentation

◆ createStorage()

static void SbThreadLocalStorage::createStorage ( size_t &  classThreadId,
const size_t  byteSize,
SoInitTLSClassCB initFunc = NULL,
SoExitTLSClassCB exitFunc = NULL,
const char *  funcName = NULL 
)
static

Creates or updates the local storage for the current thread.

Requests that 'size' bytes of storage should be allocated for all threads for the calling class. Returns a unique classThreadId to be used by getStorage method to access the storage. Used by SB_THREAD_INIT_CLASS

◆ deleteStorage()

static void SbThreadLocalStorage::deleteStorage ( size_t &  classThreadId,
const char *  funcName = NULL 
)
static

Deletes the local storage for all threads.

Used by SB_THREAD_EXIT_CLASS macro.

◆ getStorage()

static void * SbThreadLocalStorage::getStorage ( const size_t  classThreadId)
static

Returns a pointer on the storage for the given classThreadId.

This storage is guaranteed to be local to the current thread. The size of the storage is defined by what was requested by createStorage, unless the pointer returned is NULL.

If the storage has not been created, then it will create it if possible.

◆ isInitialized()

static bool SbThreadLocalStorage::isInitialized ( const size_t  classThreadId)
static

Returns true if a TLS storage has already been allocated for the given classThreadId.

The method is used in exitTLSClass() implementation to avoid calling getStorage() which will create the TLS if not found, which is useless as the purpose of exitTLSClass() is to delete associated resources. Used by SB_THREAD_IS_INITIALIZED macro.

Friends And Related Symbol Documentation

◆ GET_THREAD_LOCAL_STORAGE

#define GET_THREAD_LOCAL_STORAGE (   _className_)     (static_cast<void *> (SbThreadLocalStorage::getStorage(_className_::MT_Id)))
related

Returns pointer to current thread storage for defined class.

Definition at line 84 of file SbThreadLocalStorage.h.

◆ GET_THREAD_LOCAL_VAR

#define GET_THREAD_LOCAL_VAR (   _className_,
  _structName_,
  _varName_ 
)     ((static_cast<struct _className_::_structName_ *> (SbThreadLocalStorage::getStorage(_className_::MT_Id)))->_varName_)
related

Gets direct access to current thread storage inside variable.

Definition at line 76 of file SbThreadLocalStorage.h.

◆ SB_THREAD_EXIT_CLASS

#define SB_THREAD_EXIT_CLASS (   _className_)     SbThreadLocalStorage::deleteStorage( _className_::MT_Id, OIV_FUNCTION );
related

Requests deallocation of thread local storage.

This macro should be called within exitClass(). The structName argument should be the structure (the type name) defining what size of memory should be allocated for each thread, for this class

Definition at line 68 of file SbThreadLocalStorage.h.

◆ SB_THREAD_INIT_CLASS

#define SB_THREAD_INIT_CLASS (   _className_,
  _structName_ 
)     SbThreadLocalStorage::createStorage(_className_::MT_Id, sizeof(struct _className_::_structName_), _className_::initTLSClass, _className_::exitTLSClass, OIV_FUNCTION );
related

Requests allocation of thread local storage.

This macro should be called within initClass(). The structName argument should be the structure (the type name) defining what size of memory should be allocated for each thread, for this class

Definition at line 44 of file SbThreadLocalStorage.h.

◆ SB_THREAD_IS_INITIALIZED

#define SB_THREAD_IS_INITIALIZED (   _className_)     SbThreadLocalStorage::isInitialized(_className_::MT_Id)
related

Returns true if a TLS storage has been allocated for the given classThreadId.

This MACRO is used in exitTLSClass() implementation to avoid calling getStorage() which will create the TLS if not found, which is useless as the purpose of exitTLSClass() is to delete associated resources.

Definition at line 56 of file SbThreadLocalStorage.h.

◆ SB_THREAD_TLS_HEADER

#define SB_THREAD_TLS_HEADER ( )
related
Value:
private: \ \
static size_t MT_Id; \ \
static void initTLSClass(); \ \
static void exitTLSClass()

Defines headers for required member variables in thread storage management.

Definition at line 92 of file SbThreadLocalStorage.h.

◆ SB_THREAD_TLS_SOURCE

#define SB_THREAD_TLS_SOURCE (   _className_)
related
Value:
\
size_t _className_::MT_Id = -1

Defines source for required member variables in thread storage management.

Definition at line 107 of file SbThreadLocalStorage.h.

◆ SoNodeTLS

#define SoNodeTLS   SbThreadLocalStorage
related

Compatiblity define SoNodeTLS to SbThreadLocalStorage.

Definition at line 117 of file SbThreadLocalStorage.h.


The documentation for this class was generated from the following file: