Poco

class Task

File Information

Library: Foundation
Package: Tasks
Header: Poco/Task.h

Description

A Task is a subclass of Runnable that has a name and supports progress reporting and cancellation.

A TaskManager object can be used to take care of the lifecycle of a Task.

Inheritance

Direct Base Classes: Runnable, RefCountedObject

All Base Classes: RefCountedObject, Runnable

Member Summary

Member Functions: cancel, getOwner, hasOwner, isCancelled, name, postNotification, progress, reset, run, runTask, setOwner, setProgress, setState, sleep, state, yield

Inherited Functions: duplicate, referenceCount, release, run

Enumerations

TaskState

TASK_IDLE

TASK_STARTING

TASK_RUNNING

TASK_CANCELLING

TASK_FINISHED

Constructors

Task

Task(
    const std::string & name
);

Creates the Task.

Destructor

~Task protected virtual

virtual ~Task();

Destroys the Task.

Member Functions

cancel virtual

virtual void cancel();

Requests the task to cancel itself. For cancellation to work, the task's runTask() method must periodically call isCancelled() and react accordingly.

Can be overridden to implement custom behavior, but the base class implementation of cancel() should be called to ensure proper behavior.

hasOwner inline

bool hasOwner() const;

Returns true iff the task has an owner.

isCancelled inline

bool isCancelled() const;

Returns true if cancellation of the task has been requested.

A Task's runTask() method should periodically call this method and stop whatever it is doing in an orderly way when this method returns true. If task is cancelled before it had a chance to run, runTask() will never be called.

name inline

const std::string & name() const;

Returns the task's name.

progress inline

float progress() const;

Returns the task's progress. The value will be between 0.0 (just started) and 1.0 (completed).

reset

void reset();

Sets the task's progress to zero and clears the cancel flag.

run virtual

void run();

If task has not been cancelled prior to this call, it calls the task's runTask() method and notifies the owner of the task's start and completion. If task has been cancelled prior to this call, it only sets the state to TASK_FINISHED and notifies the owner.

See also: Poco::Runnable::run()

runTask virtual

virtual void runTask() = 0;

Do whatever the task needs to do. Must be overridden by subclasses.

state inline

TaskState state() const;

Returns the task's current state.

getOwner protected inline

TaskManager * getOwner() const;

Returns the owner of the task, which may be NULL.

postNotification protected virtual

virtual void postNotification(
    Notification * pNf
);

Posts a notification to the task manager's notification center.

A task can use this method to post custom notifications about its progress.

setOwner protected

void setOwner(
    TaskManager * pOwner
);

Sets the (optional) owner of the task.

setProgress protected

void setProgress(
    float progress
);

Sets the task's progress. The value should be between 0.0 (just started) and 1.0 (completed).

setState protected

TaskState setState(
    TaskState state
);

Sets the task's state.

sleep protected

bool sleep(
    long milliseconds
);

Suspends the current thread for the specified amount of time.

If the task is cancelled while it is sleeping, sleep() will return immediately and the return value will be true. If the time interval passes without the task being cancelled, the return value is false.

A Task should use this method in favor of Thread::sleep().

yield protected

bool yield();

Yields cpu to other threads

If the task is cancelled while it is suspended, yield() will return true. If the tasks resumes without being cancelled, the return value is false.

A Task should use this method in favor of Thread::yield().