SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND


Platform::Thread
Class Task

NonCopyableType
   |
   +-Task

Implemented in:
Platform.Thread.Task.h

class Task:
private NonCopyableType

A task represents a thread object in the parent execution thread. A task is always associated with a runnable object, that is an instance of a type implementing the IRunnable interface.

Once a task is created, the runnable object's run method is invoked in a new execution thread. The thread is terminated when the run method returns, either voluntarily or by the means of an exception.

As long as the task object exists it is possible to control the associated runnable object. For instance, a parent thread holding a task object to a runnable (which runs in another thread) can send cancel and interrupt signals, query runnable thread's state, retrieve the start and finish times (if the runnable has completed execution) and more.

A thread created by a task object will continue to run even if the task object is destroyed (e.g. if it goes out of scope).

See Also:
Thread::IRunnable, Thread::TaskGroup, Thread::CancelSignal, Thread::InterruptSignal, Thread

Constructor Summarycollapse
Task(IRunnable* runnable, ExceptionHandler* ehandler = Null)
          Creates a task that starts execution of the specified runnable object in a new thread.
~Task()
          Destroys this task.

Method Summarycollapse
Void cancel()
          Sends a cancel signal to the thread associated with this task.
Long finishTime() const
          Returns the finish time of the thread associated with this task.
Handle handle() const
          Returns the system thread handle of the thread associated with this task.
Long id() const
          Returns the id of the thread associated with this task object.
Void interrupt(Int code = 0)
          Sends an interrupt signal to the thread associated with this task.
Bool join(Int milliseconds = 0)
          Blocks the calling thread until this task finishes execution.
Priority priority() const
          Returns the relative priority of the thread associated with this task.
Void priority(Priority priority) const
          Sets the relative priority of the thread associated with this task.
IRunnable* runnable() const
          Returns the runnable object associated with this task.
template <typename Type>
Type*
runnableAs() const
          Returns the runnable object associated with this task.
Long startTime() const
          Returns the start time of the thread associated with this task.
State state() const
          Returns the state of the thread associated with this task.
String toString() const
          Returns a string representation of this task.

 

Constructor Detail

Task[explicit]

Task(IRunnable* runnable, ExceptionHandler* ehandler = Null)

Creates a task that starts execution of the specified runnable object in a new thread.

Parameters:
runnable - a runnable object
ehandler - top level exception handler, if Null the default handler is provided by the platform
Throws:
TaskCreateException - if the system was unable to create a new thread
See Also:
Thread::IRunnable

~Task[nothrow]

~Task()

Destroys this task.

 

Method Detail

cancel[nothrow]

Void cancel()

Sends a cancel signal to the thread associated with this task.


finishTime[nothrow]

Long finishTime() const

Returns the finish time of the thread associated with this task. The returned time value is in milliseconds since January 1, 1970, 00:00:00 GMT. If the thread is still running this method will return zero.

Returns:
the finish time of the thread associated with this task

handle[nothrow]

Handle handle() const

Returns the system thread handle of the thread associated with this task.

Returns:
the system thread handle of the thread associated with this task
See Also:
Thread::Handle

id[nothrow]

Long id() const

Returns the id of the thread associated with this task object. A thread id is system independant and uniquely identifies a thread within the running system process. The main thread (the thread that contains program entry point) has id value zero.

Returns:
the id of the thread associated with this task object

interrupt[nothrow]

Void interrupt(Int code = 0)

Sends an interrupt signal to the thread associated with this task.

Parameters:
code - a user-defined value sent to the thread associated with this task

join

Bool join(Int milliseconds = 0)

Blocks the calling thread until this task finishes execution. The calling thread is suspended for up to the specified number of milliseconds (or indefinitely if milliseconds == 0) until this task's runnable object completes executing its run() method (either voluntarily or forcibly by the means of an interrupt or cancel signal).

Upon join()'s return in the calling thread the state of this task shall be Thread::State_Completed.

Parameters:
milliseconds - the number of milliseconds the calling thread will be kept suspended, zero means indefinitely
Returns:
True if the operation was successful, False otherwise
Throws:
Thread::CancelSignal - if the thread was cancelled
Thread::InterruptSignal - if the thread was interrupted
See Also:
Monitor::wait, Lang::TypeConcepts::SynchronizableType, Thread::State

priority[nothrow]

Priority priority() const

Returns the relative priority of the thread associated with this task.

Returns:
the relative priority of the thread associated with this task
See Also:
Thread::Priority

priority[nothrow]

Void priority(Priority priority) const

Sets the relative priority of the thread associated with this task.

Parameters:
priority - a relative priority
See Also:
Thread::Priority

runnable[nothrow]

IRunnable* runnable() const

Returns the runnable object associated with this task.

Returns:
the runnable object associated with this task
See Also:
Thread::IRunnable

runnableAs[nothrow, inline]

template <typename Type>
Type* runnableAs() const

Returns the runnable object associated with this task. The returned object is typecast to the specified type.

Returns:
the runnable object associated with this task
See Also:
Thread::IRunnable

startTime[nothrow]

Long startTime() const

Returns the start time of the thread associated with this task. The returned time value is in milliseconds since January 1, 1970, 00:00:00 GMT.

Returns:
the start time of the thread associated with this task

state[nothrow]

State state() const

Returns the state of the thread associated with this task.

Returns:
the state of the thread associated with this task
See Also:
Thread::State

toString[nothrow]

String toString() const

Returns a string representation of this task. The format of the returned string is as follows: [id=qx, name=s, state=s, priority=s, startTime=qd, finishTime=qd].

Returns:
a string representation of this task


SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND