# Poco

# class Thread

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

## Description

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.

## Inheritance

Direct Base Classes: ThreadImpl

All Base Classes: ThreadImpl

## Member Summary

Member Functions: checkInterrupted, clearInterrupt, clearTLS, current, currentOsTid, currentTid, getAffinity, getCurrentName, getMaxOSPriority, getMinOSPriority, getName, getOSPriority, getPriority, getStackSize, id, interrupt, isInterrupted, isRunning, join, makeName, name, setAffinity, setCurrentName, setName, setOSPriority, setPriority, setStackSize, sleep, start, startFunc, tid, tls, tryJoin, trySleep, uniqueId, wakeUp, yield

## Nested Classes

### class FunctorRunnable

## Types Aliases

### TID

using TID = ThreadImpl::TIDImpl;

## Enumerations

### Policy

POLICY_DEFAULT = POLICY_DEFAULT_IMPL

### Priority

Thread priorities.

PRIO_LOWEST = PRIO_LOWEST_IMPL

The lowest thread priority.

PRIO_LOW = PRIO_LOW_IMPL

A lower than normal thread priority.

PRIO_NORMAL = PRIO_NORMAL_IMPL

The normal thread priority.

PRIO_HIGH = PRIO_HIGH_IMPL

A higher than normal thread priority.

PRIO_HIGHEST = PRIO_HIGHEST_IMPL

The highest thread priority.

## Constructors

### Thread

Thread(
uint32_t sigMask = 0
);

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

The optional sigMask parameter specifies which signals should be blocked. To block a specific signal, set the corresponding bit in the sigMask. Multiple bits can be set in the mask to block multiple signals if needed.

Available on POSIX platforms only

### Thread

Thread(
const std::string & name,
uint32_t sigMask = 0
);

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

The optional sigMask parameter specifies which signals should be blocked. To block a specific signal, set the corresponding bit in the sigMask. Multiple bits can be set in the mask to block multiple signals if needed.

Available on POSIX platforms only

## Destructor

### ~Thread

~Thread();

Destroys the thread.

## Member Functions

### checkInterrupted

void checkInterrupted();

Tests whether current thread has been interrupted. Throws Poco::ThreadInterruptedException if isInterrupted() return true.

Note: The interrupted status of the thread is cleared by this method.

### clearInterrupt

void clearInterrupt();

Clear the the interrupted status.

### current

static Thread * current();

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

### currentOsTid

static long currentOsTid();

Returns the operating system specific thread ID for the current thread. On error, or if the platform does not support this functionality, it returns zero.

### currentTid

static TID currentTid();

Returns the native thread ID for the current thread.

### getAffinity

int getAffinity() const;

Returns the thread affinity. Negative value means the thread has no CPU core affinity.

### getCurrentName

static std::string getCurrentName();

Returns the name of the current thread. Support for this feature varies across platforms. Returns an empty string if not supported, on error, or if no name has been set for the thread.

### getMaxOSPriority

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 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

std::string getName() const;

Returns the name of the thread.

### getOSPriority

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.

### getPriority

Priority getPriority() const;

Returns the thread's priority.

### getStackSize

int getStackSize() const;

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

### id

int id() const;

Returns the unique thread ID of the thread.

### interrupt

void interrupt();

Interrupts this thread.

This function does not stop any event loop running on the thread and does not terminate it in any way.

See also isInterrupted().

### isInterrupted

bool isInterrupted();

Tests whether current thread has been interrupted. Return true if the task running on this thread should be stopped. An interruption can be requested by interrupt().

This function can be used to make long running tasks cleanly interruptible. Never checking or acting on the value returned by this function is safe, however it is advisable do so regularly in long running functions. Take care not to call it too often, to keep the overhead low.

See also checkInterrupted().

### isRunning

bool isRunning() const;

Returns true if the thread is running.

### join

void join();

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

### join

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

std::string name() const;

Returns the name of the thread.

### setAffinity

bool setAffinity(
int coreId
);

Sets the thread affinity to the coreID. Returns true if succesful. Returns false if not succesful or not implemented.

### setCurrentName

static void setCurrentName(
const std::string & name
);

Sets the name of the current thread. Support for this feature varies across platforms. Any errors are silently ignored.

### setName

void setName(
const std::string & name
);

Sets the name of the thread. Note that it only take effect before start method invoked.

### setOSPriority

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.

### setPriority

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

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 void sleep(
long milliseconds
);

Suspends the current thread for the specified amount of time.

### start

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.

### start

void start(
Poco::SharedPtr < Runnable > pTarget
);

Starts the thread with the given target.

The Thread ensures that the given target stays alive while the thread is running.

### start

void start(
Callable target,
void * pData = nullptr
);

Starts the thread with the given target and parameter.

### startFunc

template < class Functor > void startFunc(
const Functor & fn
);

Starts the thread with the given functor object or lambda.

### startFunc

template < class Functor > void startFunc(
Functor && fn
);

Starts the thread with the given functor object or lambda.

### tid

TID tid() const;

Returns the native thread ID of the thread.

### tryJoin

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 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).

Note that, unlike Thread::sleep(), this function can only be succesfully called from a thread started as Poco::Thread.

### wakeUp

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 void yield();

Yields cpu to other threads.

### clearTLS

void clearTLS();

Clears the thread's local storage.

### makeName

std::string makeName();

Creates a unique name for a thread.

### tls

ThreadLocalStorage & tls();

Returns a reference to the thread's local storage.

### uniqueId

static int uniqueId();

Creates and returns a unique id for a thread.