tsc_MonitorThread

This class is used to create and run another thread.  The thread will run using the SCAPI event and wait model, like other 'normal' plugin code. 

tsc_MonitorThread is used to create and implement a thread which can subclass from monitor interfaces and process Survey Core events. Only use this class when there is no other convenient object (such as a form) that can be used for monitoring the events.

To send events between this thread and other threads, use tsc_Event and tsc_EventDelegate. To run a timer, use tsc_ITimerMonitor. The thread is generally thread-safe, since event handlers are always called on the correct thread. Resources shared with other threads may still require locking.

tsc_MonitorThread can not be used for code that calls Windows API functions that block such as WaitForSingleObject().  For this, use tsc_Thread instead.   Windows API functions that block the thread will stop the message pump and therefore block all monitored events, although they will be queued.

A tsc_MonitorThread instance can not be copied or assigned, and may only be passed by reference.

Public methods

void StartThread (tsc_Object* startData);
Creates and starts a new thread. OnStart() is called on the new thread, after which the thread enters a wait, ready to process any events that it is monitoring.   The startData object is passed to the OnStart event handler as soon as the new thread starts.

void StopThread (tsc_Object* stopData);
Signals the thread to stop. This function is thread-safe and may be called from any thread. The stopData object is passed to the OnStop handler just before the thread exits.

bool IsActive ();
Inherited. Returns true if this plugin is currently the active application. This method returns false when another application is running, and in this state all threads must be careful not to alter the current state of Survey Core, such as Launching a UITask or opening a job.

bool IsRunning ();
Inherited. Returns true if this thread has been started and hasn't yet stopped.

HANDLE GetHandle();
Gets a handle to the thread which is suitable for use in Windows API calls.

bool Sleep (double seconds);
Inherited. Suspends execution of the thread for the given duration. Monitors remain responsive, and event handlers may be called recursively during the sleep. Returns true normally, or false if the thread was stopped during the sleep, which may have shortened the sleep time.

virtual void OnStart (tsc_Object* startData);
This handler is called when the thread is first started. The startData object comes from the StartThread call that started this thread. OnStart is the best place to Start any event monitors or delegates.

virtual void OnStop (tsc_Object* stopData);
This handler is called just before the thread terminates. This is the best place to Stop any event monitors. A thread is stopped by calling StopThread() or by the Application exiting. The stopData object is the object passed to StopThread(), or NULL if the application is exiting.

~tsc_MonitorThread();
Destruction of this class will stop the thread immediately without calling OnStop. Destruction of the class while the thread is blocked in a Windows API call may cause unfathomable crashes.