class Poco::Thread

Overview

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

#include <Thread.h>

class Thread: private Poco::ThreadImpl
{
public:
    // typedefs

    typedef ThreadImpl::TIDImpl TID;
    typedef void (*Callable)(void *);

    // enums

    enum Policy;
    enum Priority;

    // classes

    template <class Functor>
    class FunctorRunnable;

    // construction

    Thread();
    Thread(const std::string& name);

    // methods

    int
    id() const;

    TID
    tid() const;

    std::string
    name() const;

    std::string
    getName() const;

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

    void
    setPriority(Priority prio);

    Priority
    getPriority() const;

    void
    setOSPriority(
        int prio,
        int policy = POLICY_DEFAULT
        );

    int
    getOSPriority() const;

    void
    setStackSize(int size);

    int
    getStackSize() const;

    void
    start(Runnable& target);

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

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

    void
    join();

    void
    join(long milliseconds);

    bool
    tryJoin(long milliseconds);

    bool
    isRunning() const;

    void
    wakeUp();

    static
    int
    getMinOSPriority(int policy = POLICY_DEFAULT);

    static
    int
    getMaxOSPriority(int policy = POLICY_DEFAULT);

    static
    bool
    trySleep(long milliseconds);

    static
    void
    sleep(long milliseconds);

    static
    void
    yield();

    static
    Thread*
    current();

    static
    TID
    currentTid();

protected:
    // methods

    ThreadLocalStorage&
    tls();

    void
    clearTLS();

    std::string
    makeName();

    static
    int
    uniqueId();
};

Inherited Members

public:
    // typedefs

    typedef pthread_t TIDImpl;
    typedef int TIDImpl;
    typedef unsigned(__stdcall* Entry)(void *);
    typedef DWORD TIDImpl;
    typedef void (*Callable)(void *);
    typedef DWORD(WINAPI* Entry)(LPVOID);

    // enums

    enum
    {
        DEFAULT_THREAD_STACK_SIZE = 65536,
    };

    enum Policy;
    enum Priority;

    // structs

    struct CallbackData;
    struct ThreadData;

    // classes

    class CurrentThreadHolder;

    // methods

    TIDImpl
    tidImpl() const;

    void
    setOSPriorityImpl(
        int prio,
        int policy = SCHED_OTHER
        );

    void
    startImpl(Runnable& target);

    void
    startImpl(
        Callable target,
        void* pData = 0
        );

    TIDImpl
    tidImpl() const;

    void
    setPriorityImpl(int prio);

    int
    getPriorityImpl() const;

    void
    setOSPriorityImpl(
        int prio,
        int policy = 0
        );

    int
    getOSPriorityImpl() const;

    void
    setStackSizeImpl(int size);

    int
    getStackSizeImpl() const;

    void
    startImpl(SharedPtr<Runnable> pTarget);

    void
    joinImpl();

    bool
    joinImpl(long milliseconds);

    bool
    isRunningImpl() const;

    static
    int
    getMinOSPriorityImpl(int policy);

    static
    int
    getMaxOSPriorityImpl(int policy);

    static
    void
    sleepImpl(long milliseconds);

    static
    void
    yieldImpl();

    static
    int
    getMinOSPriorityImpl(int policy);

    static
    int
    getMaxOSPriorityImpl(int policy);

    static
    void
    sleepImpl(long milliseconds);

    static
    void
    yieldImpl();

    static
    ThreadImpl*
    currentImpl();

    static
    TIDImpl
    currentTidImpl();

protected:
    // methods

    static
    void*
    runnableEntry(void* pThread);

    static
    int
    mapPrio(
        int prio,
        int policy = SCHED_OTHER
        );

    static
    int
    reverseMapPrio(
        int osPrio,
        int policy = SCHED_OTHER
        );

    static
    void
    runnableEntry(
        void* pThread,
        int,
        int,
        int,
        int,
        int,
        int,
        int,
        int,
        int
        );

    static
    void
    callableEntry(
        void* pThread,
        int,
        int,
        int,
        int,
        int,
        int,
        int,
        int,
        int
        );

    static
    int
    mapPrio(int prio);

    static
    int
    reverseMapPrio(int osPrio);

    static
    unsigned __stdcall
    runnableEntry(void* pThread);

    static
    DWORD WINAPI
    runnableEntry(LPVOID pThread);

    void
    createImpl(
        Entry ent,
        void* pData
        );

    void
    threadCleanup();

Detailed Documentation

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.

Construction

Thread()

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

Thread(const std::string& name)

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

Methods

int
id() const

Returns the unique thread ID of the thread.

TID
tid() const

Returns the native thread ID of the thread.

std::string
name() const

Returns the name of the thread.

std::string
getName() const

Returns the name of the thread.

void
setName(const std::string& name)

Sets the name of the thread.

void
setPriority(Priority prio)

Sets the thread’s priority.

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

Priority
getPriority() const

Returns the thread’s priority.

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.

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.

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.

int
getStackSize() const

Returns the thread’s stack size in bytes.

If the default stack size is used, 0 is returned.

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.

template <class Functor>
void
startFunc(Functor fn)

Starts the thread with the given functor object or lambda.

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.

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.

bool
isRunning() const

Returns true if the thread is running.

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.

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.

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.

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

static
void
sleep(long milliseconds)

Suspends the current thread for the specified amount of time.

static
void
yield()

Yields cpu to other threads.

static
Thread*
current()

Returns the Thread object for the currently active thread.

If the current thread is the main thread, 0 is returned.

static
TID
currentTid()

Returns the native thread ID for the current thread.

ThreadLocalStorage&
tls()

Returns a reference to the thread’s local storage.

void
clearTLS()

Clears the thread’s local storage.

std::string
makeName()

Creates a unique name for a thread.

static
int
uniqueId()

Creates and returns a unique id for a thread.