History of triggerThread

== Syntax ==

:int triggerThread(int n, int event, int previous)

== Arguments ==

:n

:: An integer index which will be passed to the thread as parameter n. This value may be used however you please, but is typically used to select which routine will be executed within the OnCtl handler. If event is FME_CUSTOMEVENT, then n may be any integer value; otherwise, n must be a value between 0 and (N_CTLS)?-1 (i.e., between 0 and 255, inclusive, in current FM releases).

:event

:: An integer value which is typically set to the code for one of the FilterMeister Events. This value will be passed to the thread as parameter e, and is used to detect that a thread trigger event has occurred within the OnCtl handler.

:previous

:: An integer value which will be passed to the thread as parameter previous. This value may be used to pass any value you want to the thread. For control events that are triggered by FM itself (using triggerEvent), the previous value usually contains the previous value of a control. With triggerThread() you can use previous to pass an additional parameter, such as a thread ID, to your thread.

== Return ==

:Returns the handle of the created thread if successful. Returns 0 if it failed (e.g., n is out of range when event is FME_CUSTOMEVENT; or memory could not be allocated for a new thread context record; or the Windows CreateThread API failed).

== Description ==

:This function creates a worker thread and schedules it to execute the OnCtl handler, passing it three parameters which may be accessed in OnCtl() as n, e, and previous, respectively. n is typically a function code specifying what section of OnCtl contains the code to be executed. e is typically FME_CUSTOMEVENT. The previous parameter may be used for any desired purpose.

<code>

</code>

:triggerThread() is almost identical to triggerEvent(). The only difference is that triggerEvent executes the OnCtl handler directly in the current thread, while triggerThread causes the OnCtl handler to be executed in a new worker thread.

== Example[[Anchor example]] ==

<code>

%fml

int nTile;

OnFilterStart:

nTile = 0;

isTileable = true;

return false;

ForEveryTile:

int ncpus = countProcessors();

nTile++;

for (int i=0; i < ncpus; i++) {

//create 'ncpus' worker threads to execute function 99

int hThread = triggerThread(99, FME_CUSTOMEVENT, i);

if (hThread==0) {

ErrorOk("Failed to create thread %d in tile %d", i, nTile);

return false;

}

}

waitForThread(0, INFINITE, 0);

Info("Tile %d is done!", nTile);

return true; //finished processing

OnCtl(n,e):

switch (e) {

case FME_CUSTOMEVENT:

switch (n) {

case 99: //function 99

//'previous' has our thread ID

Info("Thread %d is executing", previous);

//do some useful work here...

return true;

default:

Warn("Unknown thread function %d", n);

return false;

}//switch n

break;

default:

//probably a control event

return false;//process it

}//switch e

return false;

</code>

== Also see ==

:System Functions, Multithreading Functions, Events, FME_CUSTOMEVENT, triggerEvent, countProcessors, waitForThread, isThreadActive, getThreadRetVal, terminateThread

== Comments ==

:Everyone can add his or her comments about his or her experiences with this function here. Tips for using it are welcome, too.