|
OpenTop 1.3 | |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | Cross-Platform C++ | ||||
SUMMARY: CONSTRUCTOR | METHOD | DETAIL: CONSTRUCTOR | METHOD |
#include "ot/base/Thread.h"
An application may contain many threads, each one executing concurrently to perform a certain task. Every thread has a priority. Where the underlying threading system supports it, threads with a higher priority are executed in preference to threads with a lower priority. The priority of a thread is initially set equal to the thread that created it.
Not all threads will have a Thread object associated with them; only those created using an instance of the Thread class. For example, the thread that executes the main() function when an application starts is created by the operating system and does not have a Thread object. Calls to CurrentThread() will therefore yield a null reference for this thread.
When an application terminates by returning from main(), the operating system terminates any threads that are still executing. The Thread class creates two types of thread: daemon threads and user threads. The only distinction between the two is that user threads are required to terminate before the application terminates whereas daemon threads may be terminated automatically by the operating system.
Applications should include an instance of SystemMonitor in their main() function to ensure System::Terminate() is called at exit. In addition to its other tasks, System::Terminate() checks that all user threads have terminated before proceeding.
There are two ways to create a new thread of execution. One is to declare a class derived from Thread and override the virtual run() method. An instance of this class can then be created and the start() method called. For example, here is a function that uses a specialized thread to simply print "Hello World!" to the console:
class HelloThread : public Thread { public: virtual void run() { Console::cout() << OT_T("Hello World!"); } }; void hello() { RefPtr<Thread> rpThread = new HelloThread; rpThread->start(); rpThread->join(); // wait for thread termination }
The other way is to declare a class derived from Runnable which has a single virtual run() method that should be overridden to perform the required task. An instance of this class can then be passed to a Thread's constructor and the thread will call the run() method for that class. See Runnable for an example of this method.
Due to its nature, a Thread instance is likely to be accessed from more than one thread. For this reason, all access to member state information is synchronized so that it may safely be accessed by multiple concurrent threads.
A Thread object should never be allocated on the stack as stack-based objects are not consistent with the semantics of reference-counting.
Constructor/Destructor Summary | |
Thread() Constructs a Thread using this as the Runnable object and with an automatically generated name. | |
Thread(Runnable* pTarget) Constructs a thread with pTarget as the Runnable object and with an automatically generated name. | |
Thread(const String& name) Constructs a Thread with the specified name, using this as the Runnable object. | |
Thread(Runnable* pTarget, const String& name) Constructs a Thread with the specified name and Runnable object. | |
~Thread() Releases resources associated with the Thread. |
Method Summary | |
static RefPtr< Thread > |
CurrentThread() Returns a reference to the Thread object for the currently executing thread. |
static ThreadId |
CurrentThreadId() Returns a ThreadId representing the currently executing thread. |
static size_t |
GetActiveCount() Returns the number of active Threads. |
static ThreadList |
GetActiveThreads() Returns a list containing references to all the active Thread objects in the system. |
ThreadId |
getId() const Returns the ThreadId for this Thread. |
static int |
GetInterruptSignal() Returns the signal number that OpenTop will use for thread interruption. |
String |
getName() const Returns the name of this Thread. |
unsigned |
getPriority() const Returns this Thread's priority. |
void |
interrupt() Interrupts this thread. |
bool |
interruptSupported() const Tests whether the interrupt() method is supported on the current platform. |
bool |
isActive() const Tests to see if this Thread is active. |
bool |
isDaemon() const Tests whether this Thread is a daemon thread. |
void |
join() Waits for this Thread to terminate. |
void |
join(long millis) Waits up to millis milliseconds for this Thread to terminate. |
bool |
operator!=(const Thread& rhs) const Inequality operator. |
bool |
operator==(const Thread& rhs) const Equality operator. |
virtual void |
run() If this thread was constructed using a separate Runnable object, then that Runnable object's run() method is called; otherwise, this method does nothing and returns. |
void |
setDaemon(bool bDaemon) Marks this thread as either a daemon thread or a user thread. |
static void |
SetInterruptSignal(int signo) Specifies the signal number to use for interrupt processing in the UNIX environment. |
void |
setName(const String& name) Sets the name of this Thread. |
void |
setPriority(unsigned priority) Sets the Thread's execution priority. |
static void |
Sleep(long millis) Suspends execution of the currently executing thread for millis milliseconds or until the current thread is interrupted. |
static void |
Sleep(long millis, long nanos) Suspends execution of the currently executing thread for a specified duration. |
void |
start() Causes the Thread to begin execution. |
static void |
Yield() Yields any remaining execution time-slice to another thread. |
Methods inherited from class ot::ManagedObject |
addRef, getRefCount, onFinalRelease, operator=, release |
Methods inherited from class ot::Monitor |
notify, notifyAll, wait, wait |
Methods inherited from class ot::SynchronizedObject |
lock, unlock |
Typedefs |
typedef std::list< RefPtr< Thread > > ThreadList
Enumerations |
enum { |
MinPriority =1, |
|
|
NormPriority =5, |
|
|
MaxPriority =10} |
|
Constructor/Destructor Detail |
protected Thread()
Automatically generated names are of the form "Thread-"+n, where n is an integer.
Thread(Runnable* pTarget)
pTarget
- protected Thread(const String& name)
name
- Thread(Runnable* pTarget, const String& name)
pTarget
- name
- ~Thread()
Method Detail |
static RefPtr< Thread > CurrentThread()
static ThreadId CurrentThreadId()
static size_t GetActiveCount()
A Thread becomes active during the call to start() and ceases to be active after the run() method has completed and shortly before it is terminated by the operating system.
static ThreadList GetActiveThreads()
ThreadId getId() const
static int GetInterruptSignal()
String getName() const
unsigned getPriority() const
void interrupt()
On most UNIX platforms, blocking i/o calls can be interrupted, but this is not portable behaviour.
Interruption is implemented differently on the various supported platforms.
If your application is going to call interrupt() in the UNIX environment, you must choose which signal number to assign and call SetInterruptSignal() during initialization.
UnsupportedOperationException
- RuntimeException
- bool interruptSupported() const
bool isActive() const
bool isDaemon() const
void join()
InterruptedException
- void join(long millis)
millis
- InterruptedException
- bool operator!=(const Thread& rhs) const
bool operator==(const Thread& rhs) const
virtual void run()
This method runs in the context of a newly created thread of execution. The thread of execution is terminated when this method returns.
void setDaemon(bool bDaemon)
An application exits when the only threads left executing are daemon threads. This policy is enforced by the System::Terminate() function, which is called by SystemMonitor's destructor.
Some care should be taken when deciding whether or not to employ daemon threads. The advantage of using a daemon thread is that the application doesn't need to worry about terminating it, but the flip-side is that the thread could be terminated at any point - even when it is doing important work. Another draw-back with using daemon threads is that memory resources used by the thread may not be freed prior to system termination - which could result in memory diagnostic tools indicating a memory leak in the application.
IllegalThreadStateException
- static void SetInterruptSignal(int signo)
UNIX signal handling is process-wide and non-modular. If one thread sets a signal handler, all threads get to use the same one. For this reason signal handling is normally dealt with at the application level rather than by individual libraries. This method gives applications the choice of which signal number to assign to OpenTop for thread interruption.
If your application does not use the alarm() function then SIGALRM is a good choice. Note, though, that SIGALRM is not defined in the Windows version of <signal.h>, so conditional code is required. For example:-
#include "ot/base/SystemMonitor.h" #include "ot/base/Thread.h" #include <signal.h> using namespace ot; int main(int argc, char* argv[]) { SystemMonitor monitor; // ensure correct termination // Assign an unused signal for UNIX thread interruption handling #ifdef SIGALRM Thread::SetInterruptSignal(SIGALRM); #endif ... }
signo
- void setName(const String& name)
void setPriority(unsigned priority)
A thread's execution priority may be altered both before and during its execution.
Not all operating systems support the setting of a thread's execution priority. In this case calling this function does nothing.
IllegalArgumentException
- static void Sleep(long millis)
This function is also available in single-threaded versions of OpenTop.
millis
- InterruptedException
- static void Sleep(long millis, long nanos)
This is a static function that can be called from any thread, even from those threads that are not created and controlled by a Thread object (such as the application's main thread).
This function is also available in single-threaded versions of OpenTop.
millis
- nanos
- InterruptedException
- void start()
IllegalThreadStateException
- static void Yield()
|
OpenTop 1.3 | |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | Cross-Platform C++ | ||||
SUMMARY: CONSTRUCTOR | METHOD | DETAIL: CONSTRUCTOR | METHOD |