Class Poco::ThreadPool

File Information

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

Description

A thread pool always keeps a number of threads running, ready to accept work. Creating and starting a threads can impose a significant runtime overhead to an application. A thread pool helps to improve the performance of an application by reducing the number of threads that have to be created (and destroyed again). Threads in a thread pool are re-used once they become available again. The thread pool always keeps a minimum number of threads running. If the demand for threads increases, additional threads are created. Once the demand for threads sinks again, no-longer used threads are stopped and removed from the pool.

Member Summary

Member Functions: addCapacity, allocated, available, capacity, collect, createThread, defaultPool, getStackSize, getThread, housekeep, joinAll, name, setStackSize, start, startWithPriority, stopAll, used

Constructors

ThreadPool

ThreadPool(
    int minCapacity = 2,
    int maxCapacity = 16,
    int idleTime = 60,
    int stackSize = 0
);

Creates a thread pool with minCapacity threads. If required, up to maxCapacity threads are created a NoThreadAvailableException exception is thrown. If a thread is running idle for more than idleTime seconds, and more than minCapacity threads are running, the thread is killed. Threads are created with given stack size.

ThreadPool

ThreadPool(
    const std::string & name,
    int minCapacity = 2,
    int maxCapacity = 16,
    int idleTime = 60,
    int stackSize = 0
);

Creates a thread pool with the given name and minCapacity threads. If required, up to maxCapacity threads are created a NoThreadAvailableException exception is thrown. If a thread is running idle for more than idleTime seconds, and more than minCapacity threads are running, the thread is killed. Threads are created with given stack size.

Destructor

~ThreadPool

~ThreadPool();

Currently running threads will remain active until they complete.

Member Functions

addCapacity

void addCapacity(
int n
);

Increases (or decreases, if n is negative) the maximum number of threads.

allocated

int allocated() const;

Returns the number of currently allocated threads.

available

int available() const;

Returns the number available threads.

capacity

int capacity() const;

Returns the maximum capacity of threads.

collect

void collect();

Stops and removes no longer used threads from the thread pool. Can be called at various times in an application's life time to help the thread pool manage its threads. Calling this method is optional, as the thread pool is also implicitly managed in calls to start(), addCapacity() and joinAll().

defaultPool

static ThreadPool & defaultPool();

Returns a reference to the default thread pool.

getStackSize

int getStackSize() const;

Returns the stack size used to create new threads.

joinAll

void joinAll();

Waits for all threads to complete.

Note that this will not actually join() the underlying thread, but rather wait for the thread's runnables to finish.

name

const std::string & name() const;

Returns the name of the thread pool, or an empty string if no name has been specified in the constructor.

setStackSize

void setStackSize(
int stackSize
);

Sets the stack size for threads. New stack size applies only for newly created threads.

start

void start(
Runnable & target
);

Obtains a thread and starts the target. Throws a NoThreadAvailableException if no more threads are available.

start

void start(
Runnable & target,
const std::string & name
);

Obtains a thread and starts the target. Assigns the given name to the thread. Throws a NoThreadAvailableException if no more threads are available.

startWithPriority

void startWithPriority(
Thread::Priority priority,
Runnable & target
);

Obtains a thread, adjusts the thread's priority, and starts the target. Throws a NoThreadAvailableException if no more threads are available.

startWithPriority

void startWithPriority(
    Thread::Priority priority,
    Runnable & target,
    const std::string & name
);

Obtains a thread, adjusts the thread's priority, and starts the target. Assigns the given name to the thread. Throws a NoThreadAvailableException if no more threads are available.

stopAll

void stopAll();

Stops all running threads and waits for their completion.

Will also delete all thread objects. If used, this method should be the last action before the thread pool is deleted.

Note: If a thread fails to stop within 10 seconds (due to a programming error, for example), the underlying thread object will not be deleted and this method will return anyway. This allows for a more or less graceful shutdown in case of a misbehaving thread.