class Thread

Library: Foundation
Package: Threading
Header: Poco/Thread.h


This class implements a platform-independent wrapper to an operating system thread.

Every Thread object gets a unique (within its process) numeric thread ID. Furthermore, a thread can be assigned a name. The name of a thread can be changed at any time.


Direct Base Classes: ThreadImpl

All Base Classes: ThreadImpl

Member Summary

Member Functions: clearTLS, current, currentTid, getMaxOSPriority, getMinOSPriority, getName, getOSPriority, getPriority, getStackSize, id, isRunning, join, makeName, name, setName, setOSPriority, setPriority, setStackSize, sleep, start, startFunc, tid, tls, tryJoin, trySleep, uniqueId, wakeUp, yield

Nested Classes

class FunctorRunnable protected




typedef ThreadImpl::TIDImpl TID;





Thread priorities.


The lowest thread priority.


A lower than normal thread priority.


The normal thread priority.


A higher than normal thread priority.


The highest thread priority.




Creates a thread. Call start() to start it.


    const std::string & name

Creates a named thread. Call start() to start it.




Destroys the thread.

Member Functions

current static inline

static Thread * current();

Returns the Thread object for the currently active thread. If the current thread is the main thread, 0 is returned.

currentTid static inline

static TID currentTid();

Returns the native thread ID for the current thread.

getMaxOSPriority static inline

static int getMaxOSPriority(
    int policy = POLICY_DEFAULT

Returns the maximum operating system-specific priority value, which can be passed to setOSPriority() for the given policy.

getMinOSPriority static inline

static int getMinOSPriority(
    int policy = POLICY_DEFAULT

Returns the minimum operating system-specific priority value, which can be passed to setOSPriority() for the given policy.

getName inline

std::string getName() const;

Returns the name of the thread.

getOSPriority inline

int getOSPriority() const;

Returns the thread's priority, expressed as an operating system specific priority value.

May return 0 if the priority has not been explicitly set.


Priority getPriority() const;

Returns the thread's priority.

getStackSize inline

int getStackSize() const;

Returns the thread's stack size in bytes. If the default stack size is used, 0 is returned.

id inline

int id() const;

Returns the unique thread ID of the thread.

isRunning inline

bool isRunning() const;

Returns true if the thread is running.


void join();

Waits until the thread completes execution. If multiple threads try to join the same thread, the result is undefined.


void join(
    long milliseconds

Waits for at most the given interval for the thread to complete. Throws a TimeoutException if the thread does not complete within the specified time interval.

name inline

std::string name() const;

Returns the name of the thread.


void setName(
    const std::string & name

Sets the name of the thread.

setOSPriority inline

void setOSPriority(
    int prio,
    int policy = POLICY_DEFAULT

Sets the thread's priority, using an operating system specific priority value. Use getMinOSPriority() and getMaxOSPriority() to obtain mininum and maximum priority values. Additionally, a scheduling policy can be specified. The policy is currently only used on POSIX platforms where the values SCHED_OTHER (default), SCHED_FIFO and SCHED_RR are supported.


void setPriority(
    Priority prio

Sets the thread's priority.

Some platform only allow changing a thread's priority if the process has certain privileges.

setStackSize inline

void setStackSize(
    int size

Sets the thread's stack size in bytes. Setting the stack size to 0 will use the default stack size. Typically, the real stack size is rounded up to the nearest page size multiple.

sleep static inline

static void sleep(
    long milliseconds

Suspends the current thread for the specified amount of time.


void start(
    Runnable & target

Starts the thread with the given target.

Note that the given Runnable object must remain valid during the entire lifetime of the thread, as only a reference to it is stored internally.


void start(
    Callable target,
    void * pData = 0

Starts the thread with the given target and parameter.

startFunc inline

template < class Functor > void startFunc(
    Functor fn

Starts the thread with the given functor object or lambda.

tid inline

TID tid() const;

Returns the native thread ID of the thread.


bool tryJoin(
    long milliseconds

Waits for at most the given interval for the thread to complete. Returns true if the thread has finished, false otherwise.

trySleep static

static bool trySleep(
    long milliseconds

Starts an interruptible sleep. When trySleep() is called, the thread will remain suspended until:

  • the timeout expires or
  • wakeUp() is called

Function returns true if sleep attempt was completed, false if sleep was interrupted by a wakeUp() call. A frequent scenario where trySleep()/wakeUp() pair of functions is useful is with threads spending most of the time idle, with periodic activity between the idle times; trying to sleep (as opposed to sleeping) allows immediate ending of idle thread from the outside.

The trySleep() and wakeUp() calls should be used with understanding that the suspended state is not a true sleep, but rather a state of waiting for an event, with timeout expiration. This makes order of calls significant; calling wakeUp() before calling trySleep() will prevent the next trySleep() call to actually suspend the thread (which, in some scenarios, may be desirable behavior).


void wakeUp();

Wakes up the thread which is in the state of interruptible sleep. For threads that are not suspended, calling this function has the effect of preventing the subsequent trySleep() call to put thread in a suspended state.

yield static inline

static void yield();

Yields cpu to other threads.

clearTLS protected

void clearTLS();

Clears the thread's local storage.

makeName protected

std::string makeName();

Creates a unique name for a thread.

tls protected

ThreadLocalStorage & tls();

Returns a reference to the thread's local storage.

uniqueId protected static

static int uniqueId();

Creates and returns a unique id for a thread.



using ThreadImpl::Callable;