tsc_Thread

The tsc_Thread class provides the means to create and run other threads.

tsc_Thread is necessary when the plugin needs to call some blocking function in the Windows API (or any other API), such as WaitForSingleObject().  If such a blocking function is called directly from a normal SCAPI thread, a deadlock or unresponsive UI may result.

A tsc_Thread behaves a little differently from any other API code that is not run as a tsc_Thread; there is none of the normal resource protection that is available with other threads, and care should be taken to lock any resource that is shared with another thread.  Also,  the OnClose event handler may be called from a different thread from the tsc_Thread.  This is unlike most other SCAPI event handlers.

For a thread that asynchonously processes SCAPI events (that is, implements one or more monitors), use tsc_MonitorThread instead.

Public methods

tsc_Thread();
Constructs a new but empty thread object.

bool Start (tsc_Object* startData);
Creates a new thread, and starts execution by calling ThreadMain() on the new thread.  The startData object is passed to the new thread. Returns false if no thread was available or the maximum thread count was reached.

virtual void ThreadMain (tsc_Object* startData) = 0;
Override the ThreadMain() function in a subclass to implement the thread. When the ThreadMain function exits, the thread will terminate.  The thread function must exit as soon as possible upon receiving the OnClose event, or Survey Core may fail to shut down correctly.

virtual void OnClose() = 0;
The event is raised when the plugin is exited by the user or the tsc_Thread object is destroyed. The thread function should be made to exit immediately. Important: A different thread may call this event handler, unlike most other SCAPI event handlers.

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

bool IsRunning ();
Returns true if this thread has been started and hasn't yet stopped.  This is only useful when called from outside the tsc_Thread class; if called from any code running on the thread it will always return true.

HANDLE GetHandle();
Gets a handle to the thread which is suitable for use in Windows API calls.  Other Windows API calls may be used, such as GetCurrentThreadId() to retrieve the ID of the thread.

void DoEvents ();
Allows any pending events to be processed (eg, by Monitor interfaces).  This function is not generally useful for tsc_Thread objects.

bool Sleep (double seconds);
Suspends execution of the thread for the given duration. If this method returns false then a shutdown is in progress and the thread should exit immediately.