Editing triggerThread - FilterMeisterWiki

When saving, enter the following:

 _____  _______                     ______ 
(_   _)(_____  )                   |  ____|
  | |       /'/'  ####    ######   | |__   
  | |     /'/'     ##       ##     |  __|  
  | |   /'/'___    ##       ##     | |     
  (_)  (_______)   ##       ##     |_|     
                   ##       ##             
                  ####      ##

Visit Preferences to set your user name

= 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 ((OnCtl|FME_CUSTOMEVENT#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 ((OnCtl|FME_CUSTOMEVENT#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 ((OnCtl|FME_CUSTOMEVENT#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)), ((System Functions|Multithreading Functions#Multithreading-Functions)), ((Events)), ((OnCtl|FME_CUSTOMEVENT#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.

Summary of change:
Add document to category: