If you can read this text, it means you are not experiencing this website at its best. This website is designed for used with a standards-compliant browser.
Current version: 2.3.2
ZThreads
A platform-independent, multi-threading and synchronization library for C++
Home Documentation Downloads CVS Contact
ThreadLocal< T, InitialValueT, ChildValueT, InheritableValueT > Class Template Reference

#include <ThreadLocal.h>

Inheritance diagram for ThreadLocal< T, InitialValueT, ChildValueT, InheritableValueT >:
ThreadLocalImpl

Public Member Functions

get () const
 
void set (T v) const
 
void clear () const
 

Static Public Member Functions

static void clearAll ()
 

Detailed Description

template<typename T, typename InitialValueT = ThreadLocalImpl::InitialValueFn<T>, typename ChildValueT = ThreadLocalImpl::UniqueChildValueFn, typename InheritableValueT = ThreadLocalImpl::InheritableValueFn>
class ZThread::ThreadLocal< T, InitialValueT, ChildValueT, InheritableValueT >
Author
Eric Crahen http://www.code-foo.com
Date
<2003-07-27T11:18:21-0400>
Version
2.3.0

Provides access to store and retrieve value types to and from a thread local storage context. A thread local storage context consists of the calling thread a specific ThreadLocal object. Since this context is specific to each thread whenever a value is stored in a ThreadLocal that is accessible from multiple threads, it can only be retrieved by the thread that stored it.

The first time a thread accesses the value associated with a thread local storage context, a value is created. That value is either an initial value (determined by InitialValueT) or an inherited value (determined by ChildValueT).

  • If a threads parent had no value associated with a ThreadLocal when the thread was created, then the InitialValueT functor is used to create an initial value.
  • If a threads parent did have a value associated with a ThreadLocal when the thread was created, then the childValueT functor is used to create an initial value.

Not all ThreadLocal's support the inheritance of values from parent threads. The default behavoir is to create values through the InitialValueT functor for all thread when they first access a thread local storage context.

  • Inheritance is enabled automatically when a user supplies a ChildValueT functor other than the default one supplied.
  • Inheritance can be controlled explicitly by the user through a third functor, InheritableValueT.

Examples

Default initial value

A ThreadLocal that does not inherit, and uses the default value for an int as its initial value.

#include "zthread/ThreadLocal.h"
#include "zthread/Thread.h"
#include <iostream>
using namespace ZThread;
class aRunnable : public Runnable {
ThreadLocal<int> localValue;
public:
void run() {
std::cout << localValue.get() << std::endl;
}
};
int main() {
// Create a shared task to display ThreadLocal values
Task task(new aRunnable);
Thread t0(task); t0.wait();
Thread t1(task); t1.wait();
Thread t2(task); t2.wait();
// Output:
// 0
// 0
// 0
return 0;
}

User-specified initial value

A ThreadLocal that does not inherit, and uses a custom initial value.

#include "zthread/ThreadLocal.h"
#include "zthread/Thread.h"
#include <iostream>
using namespace ZThread;
struct anInitialValueFn {
int operator()() {
static int next = 100;
int val = next; next += 100;
return val;
}
};
class aRunnable : public Runnable {
ThreadLocal<int, anInitialValueFn> localValue;
public:
void run() {
std::cout << localValue.get() << std::endl;
}
};
int main() {
// Create a shared task to display ThreadLocal values
Task task(new aRunnable);
Thread t0(task); t0.wait();
Thread t1(task); t1.wait();
Thread t2(task); t2.wait();
// Output:
// 100
// 200
// 300
return 0;
}

User-specified inherited value

A ThreadLocal that does inherit and modify child values. (The default initial value functor is used)

#include "zthread/ThreadLocal.h"
#include "zthread/Thread.h"
#include <iostream>
using namespace ZThread;
struct anInheritedValueFn {
int operator()(int val) {
return val + 100;
}
};
// This Runnable associates no ThreadLocal value in the main thread; so
// none of the child threads have anything to inherit.
class aRunnable : public Runnable {
ThreadLocal<int, ThreadLocalImpl::InitialValueFn<int>, anInheritedValueFn> localValue;
public:
void run() {
std::cout << localValue.get() << std::endl;
}
};
// This Runnable associates a ThreadLocal value in the main thread which
// is inherited when the child threads are created.
class anotherRunnable : public Runnable {
ThreadLocal<int, ThreadLocalImpl::InitialValueFn<int>, anInheritedValueFn> localValue;
public:
anotherRunnable() {
localValue.set(100);
}
void run() {
std::cout << localValue.get() << std::endl;
}
};
int main() {
// Create a shared task to display ThreadLocal values
Task task(new aRunnable);
Thread t0(task); t0.wait();
Thread t1(task); t1.wait();
Thread t2(task); t2.wait();
// Output:
// 0
// 0
// 0
task = Task(new anotherRunnable);
Thread t10(task); t10.wait();
Thread t11(task); t11.wait();
Thread t12(task); t12.wait();
// Output:
// 200
// 200
// 200
return 0;
}

Parameters

InitialValueT

This template parameter should indicate the functor used to set the initial value. It should support the following operator:

// required operator T operator()

// supported expression InitialValueT()()

ChildValueT

This template parameter should indicate the functor used to set the value that will be inherited by thread whose parent have associated a value with the ThreadLocal's context at the time they are created. It should support the following operator:

// required operator T operator(const T& parentValue)

// supported expression ChildValueT()(parentValue)

InheritableValueT

This template parameter should indicate the functor, used to determine wheather or not this ThreadLocal will allow values from a parent threads context to be inherited by child threads when they are created. It should support the following operator:

// required operator bool operator(const T& childValueFunctor)

// supported expression InheritableValueT()( ChildValueT() )

Member Function Documentation

◆ clear()

void clear ( ) const
inline

Remove any value current associated with this ThreadLocal.

Postcondition
Upon thier next invocation the get() and set() functions will behave as if no value has been associated with this ThreadLocal and an initial value will be generated.

◆ clearAll()

static void clearAll ( )
inlinestatic

Remove any value current associated with any ThreadLocal.

Postcondition
Upon thier next invocation the get() and set() functions will behave as if no value has been associated with any ThreadLocal and new initial values will be generated.

◆ get()

T get ( ) const
inline

Get the value associated with the context (this ThreadLocal and the calling thread) of the invoker. If no value is currently associated, then an intial value is created and associated; that value is returned.

Returns
T associated value.
Postcondition
If no value has been associated with the invoking context then an inital value will be associated. That value is created by the InitialValueT functor.

◆ set()

void set ( v) const
inline

Replace the value associated with the context (this ThreadLocal and the calling thread) of the invoker. If no value is currently associated, then an intial value is first created and subsequently replaced by the new value.

Parameters
vvalue of type T to associate.
Postcondition
If no value has been associated with the invoking context then an inital value will first be associated. That value is created by the InitialValueT functor and then replaced with the new value.

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