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


Namespace Platform::Thread

namespace Platform::Thread

Provides synchronization primitives and constructs allowing creation and control of execution threads.

Inner Compounds, Typedefs, and Enumscollapse
class CancelSignal
          Represents a cancel signal.
struct Communicator
          Provides a way to communicate between threads using message passing.
class ExceptionHandler
          Provides an interface for top level exception handling used by new threads.
class ILockable
          Defines an interface to be implemented by synchronization types with acquire-release semantics.
class InterruptSignal
          Represents an interrupt signal.
class IRunnable
          Represents the runnable interface.
class Lock
          Represents a scope based lock for objects implementing ILockable interface.
class Monitor
          Represents a monitor synchronization primitive.
class Mutex
          Represents a mutex synchronization primitive.
class Task
          A task represents a thread object in the parent execution thread.
class TaskCreateException
          Thrown when a task constructor fails to create a new execution thread.
class TaskGroup
          A task group represents a set of tasks, each running in its own execution thread.
typedef Handle
          Represents the type of a system thread handle.
enum Priority
          Represents the relative priority of a thread.
enum State
          Represents the current state of an execution thread.

Method Summarycollapse
Handle handle()
          Retrieves the system thread handle for the calling thread.
Bool hasPendingInterrupts()
          Tests whether the calling thread has pending interrupts.
Long id()
          Returns the id of the calling thread.
Bool isCanceled()
          Tests whether the calling thread has received a cancel signal.
Bool isInterrupted(Int& code)
          Tests whether the calling thread has received an interrupt signal.
Int notify(const Lang::TypeConcepts::SynchronizableType* object)
          Unblocks one thread (if any) waiting on the specified object's monitor.
Int notifyAll(const Lang::TypeConcepts::SynchronizableType* object)
          Unblocks all the threads (if any) waiting on the specified object's monitor.
Priority priority()
          Returns the relative priority of the calling thread.
Void priority(Priority priority)
          Sets the relative priority of the calling thread.
Void sleep(Int milliseconds = 0)
          Suspends the calling thread for the specified amount of time.
Long startTime()
          Retrieves the start time of the calling thread.
Bool wait(const Lang::TypeConcepts::SynchronizableType* object, Int milliseconds = 0)
          Suspends (blocks) the calling thread and places it in the waiting queue of the specified object's monitor.
Void yield()
          Signals the system scheduler that the calling thread is willing to release its remaining time quantum thus allowing other threads to run.

 

Method Detail

handle[nothrow]

Handle handle()

Retrieves the system thread handle for the calling thread.

Returns:
the system thread handle for the calling thread
See Also:
Thread::Handle

hasPendingInterrupts[nothrow]

Bool hasPendingInterrupts()

Tests whether the calling thread has pending interrupts.

Returns:
True if the calling thread has pending interrupts, False otherwise
See Also:
Task::interrupt

id[nothrow]

Long id()

Returns the id of the calling thread. 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 calling thread

isCanceled[nothrow]

Bool isCanceled()

Tests whether the calling thread has received a cancel signal.

Returns:
True if the calling thread has received a cancel signal, False otherwise
See Also:
Task::cancel

isInterrupted[nothrow]

Bool isInterrupted(Int& code)

Tests whether the calling thread has received an interrupt signal. If the thread has been interrupted the code argument is set to the value sent from the interrupting thread.

Every thread has an interrupt FIFO queue which stores interrupt signals sent from other threads. If a thread has pending interrupts, this method will retrieve (dequeue) the first one from the queue and place the received interrupt code value into the code argument. If the queue contains more interrupts, they can be retrieved by successively calling this method until the queue is empty and this method returns False.

Returns:
True if the calling thread has received an interrupt signal, False otherwise
See Also:
Task::interrupt

notify[nothrow, inline]

Int notify(const Lang::TypeConcepts::SynchronizableType* object)

Unblocks one thread (if any) waiting on the specified object's monitor.

Parameters:
object - an object implementing SynchronizableType concept
Returns:
the number of threads that were unblocked and released from the waiting queue (i.e. zero or one)
Remarks:
If the calling thread is not the owner of the specified object's monitor this method triggers a run-time error Error_Thread_NotifyInvalidMonitor.
See Also:
Monitor::notify, Lang::TypeConcepts::SynchronizableType

notifyAll[nothrow, inline]

Int notifyAll(const Lang::TypeConcepts::SynchronizableType* object)

Unblocks all the threads (if any) waiting on the specified object's monitor.

Parameters:
object - an object implementing SynchronizableType concept
Returns:
the number of threads that were unblocked and released from the waiting queue
Remarks:
If the calling thread is not the owner of the specified object's monitor this method triggers a run-time error Error_Thread_NotifyInvalidMonitor.
See Also:
Monitor::notifyAll, Lang::TypeConcepts::SynchronizableType

priority[nothrow]

Priority priority()

Returns the relative priority of the calling thread.

Returns:
the relative priority of the calling thread
See Also:
Thread::Priority

priority[nothrow]

Void priority(Priority priority)

Sets the relative priority of the calling thread.

Parameters:
priority - the relative priority of the calling thread
See Also:
Thread::Priority

sleep

Void sleep(Int milliseconds = 0)

Suspends the calling thread for the specified amount of time. This is a blocking method. The system scheduler will not schedule the thread to run until the timeout expires. If the timeout is specified to be zero, the thread is suspended indefinitely, until other execution threads in the system explicitly notify this thread's monitor or the thread receives an interrupt or a cancel signals.

This method is an interruption- and cancellation point. If this thread's monitor receives an interrupt or cancel signals, this method will unblock the current thread and throw an exception: either Thread::CancelSignal or Thread::InterruptSignal respectively.

Parameters:
milliseconds - the timeout, in milliseconds
Throws:
Thread::InterruptSignal
Thread::CancelSignal
See Also:
Thread::notify, Thread::notifyAll, Thread::Task::join, Thread::isInterrupted, Thread::isCanceled, Thread::State

startTime[nothrow]

Long startTime()

Retrieves the start time of the calling thread. The returned time value is in milliseconds since January 1, 1970, 00:00:00 GMT.

Returns:
the start time of the calling thread
See Also:
DateTime

wait[inline]

Bool wait(const Lang::TypeConcepts::SynchronizableType* object, Int milliseconds = 0)

Suspends (blocks) the calling thread and places it in the waiting queue of the specified object's monitor.

Parameters:
object - an object implementing SynchronizableType concept
milliseconds - a timeout, in milliseconds
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

yield[nothrow]

Void yield()

Signals the system scheduler that the calling thread is willing to release its remaining time quantum thus allowing other threads to run.

Every thread in the system is allowed to run for a certain amount of time called the time quantum or time-slice. A time quantum is usually a very short timespan, commonly measured in milliseconds. Once a thread's time quantum expires the system scheduler suspends the thread and switches to (i.e. resumes or wakes up) another thread. If a given thread has completed its task or has no meaningful work to do (for instance it can be waiting for a shared resource to become available) the thread may be nice to other threads in the system by giving up its time quantum by using the yield and sleep methods.

See Also:
sleep


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