File MIES_Async.ipf

ASYNC This file holds the asynchronous execution framework

See Async Framework for the full documentation.

Variable names for free data folder structure

static const string ASYNC_THREAD_MARKER_STR = "threadDFMarker"
static const string ASYNC_WORKERFUNC_STR = "WorkerFunc"
static const string ASYNC_READOUTFUNC_STR = "ReadOutFunc"
static const string ASYNC_WORKLOADCLASS_STR = "workloadClass"
static const string ASYNC_PARAMCOUNT_STR = "paramCount"
static const string ASYNC_INORDER_STR = "inOrder"
static const string ASYNC_ABORTFLAG_STR = "abortFlag"
static const string ASYNC_ERROR_STR = "err"
static const string ASYNC_ERRORMSG_STR = "errmsg"
static const string ASYNC_WLCOUNTER_STR = "workloadClassCounter"

Functions

variable ASYNC_Start(variable numThreads, variable disableTask = defaultValue)

Starts the Async Framework with numThreads parallel threads.

Parameters:

  • numThreads – number of threads to setup for processing data, must be >= 1 and <= ASYNC_MAX_THREADS

  • disableTask – [optional, default = 0] when set to 1 the background task processing readouts is not started

Returns:

1 if ASYNC framework was started, 0 if ASYNC framework was already running, in this case the number of threads is not changed

dfref ASYNC_Worker(dfref dfr)

Prototype function for an async worker function.

Parameters:

dfr – reference to thread data folder

Returns:

data folder reference to output data folder

variable ASYNC_ReadOut(dfref dfr, variable err, string errmsg)

Prototype function for an async readout function.

Parameters:

  • dfr – reference to returned data folder from thread

  • err – error code, only set in the error case

  • errmsg – error message, only set in the error case

static variable ASYNC_Thread()

thread function that receives data folders from the thread input queue and calls the setup custom worker function. With :cpp:func:ASYNC_Start numThreads :cpp:func:ASYNC_Thread functions will be started in their own thread. Each will run until the framework is stopped. UTF_NOINSTRUMENTATION

static dfref ASYNC_Run_Worker(dfref dfr)
variable ASYNC_ThreadReadOut()

Receives data from finished workloads. Calls the user defined readout function. For in order readouts this function buffers pending result data folders until they can be processed in order.

variable ASYNC_IsWorkloadClassDone(string workloadClass, variable removeClass = defaultValue)

Allows to check if all executed work loads of a specific work load class were read out. For that case, the work load class can optionally be removed from Async.

Parameters:

  • workloadClass – [in] work load class string

  • removeClass – [in] [optional, default = 0] when set the specified work load class is removed from Async The parameter has no effect, if the work loads of the specified class are not done.

Returns:

1 if work load class finished, 0 if work load class did not finish, NaN if work load class not known to ASYNC

variable ASYNC_WaitForWLCToFinishAndRemove(string workloadClass, variable timeout)

Wait for TP analysis from specific panel to finish and remove it.

Parameters:

  • workloadClass – [in] name of work load class

  • timeout – [in] time out in seconds

Returns:

0 if work load class is unknown or has finished and was removed, 1 if timeout was encountered.

variable ASYNC_BackgroundReadOut(WMBackgroundStruct *s)

Background function that reads data folders from the thread output queue and calls the setup custom readout function The function takes care to buffer results if they should be processed in order.

Parameters:

s – default structure for Igor background tasks

variable ASYNC_AddParam(dfref dfr, wave w = defaultValue, variable var = defaultValue, string str = defaultValue, variable move = defaultValue, string name = defaultValue)

Adds one parameter to a data folder for a threaded worker execution.

The parameters are globals in the threads data folder and named param0, param1, param2… in order of adding them. Only one parameter can be added per call. move is only allowed in combination with a wave.

Parameters:

  • dfr – data folder reference to thread df, prepared by calling ASYNC_PrepareDF

  • w – [optional, default = null] wave reference of wave to be added as parameter

  • var – [optional, default = 0] variable to be added as parameter

  • str – [optional, default = 0] string to be added as parameter

  • move – [optional, default = 0] if a wave was given as parameter and move is not zero then the wave is moved to the threads data folder

  • name – [optional, default = paramXXX] name of the added parameter

wave ASYNC_FetchWave(dfref dfr, string name)

Fetch a wave from the DFREF in the worker function.

variable ASYNC_FetchVariable(dfref dfr, string name)

Fetch a variable from the DFREF in the worker function.

string ASYNC_FetchString(dfref dfr, string name)

Fetch a string from the DFREF in the worker function.

variable ASYNC_Stop(variable timeout = defaultValue, variable fromAssert = defaultValue)

Stops the Async Framework.

Parameters:

  • timeout – [optional, default = Inf] time in s to wait for running threads, the function waits for pending threads and pending readouts within this time. After a timeout happened the readout processing is stopped and threads are stopped. Any pending data is lost. If the threads have to be stopped forcefully, an assertion is raised. Using a finite timeout is strongly recommended.

  • fromAssert – [optional, default = 0] specified when called as cleanup function from ASSERT Suppresses further assertions such that all required cleanup routines such as ThreadGroupRelease are executed.

Returns:

2 if ASYNC framework was not running, 1 if a timeout was encountered, 0 otherwise

dfref ASYNC_PrepareDF(string WorkerFunc, string ReadOutFunc, string workloadClass, variable inOrder = defaultValue)

Prepares a thread data folder for use with the AsyncFramework This function should be called first when setting up a worker with parameters.

Parameters:

  • WorkerFunc – string naming a threadsafe worker function in the form of the ASYNC_Worker template

  • ReadOutFunc – string naming a readout function in the form of the ASYNC_ReadOut template

  • workloadClass – string naming a work load class for work load attribution like “TestPulse” The string must follow strict object naming rules.

  • inOrder – [optional, default = 1] flag that allows to disable in order readout of results

Returns:

data folder for thread, where parameters can be put to with :cpp:func:ASYNC_AddParam

variable ASYNC_Execute(dfref dfr)

Puts a prepared thread data folder to parallel execution in another thread.

Parameters:

dfr – data folder that is setup for thread and is to be deployed

static variable ASYNC_IsThreadDF(dfref dfr)

test if data folder is marked for thread usage

UTF_NOINSTRUMENTATION

static variable ASYNC_IsASYNCRunning()

returns 1 if ASYNC framework is running, 0 otherwise

Variables

static const string ASYNC_BACKGROUND = "AsyncFramework"
static const double ASYNC_THREAD_MARKER = 299792458
static const double ASYNC_MAX_THREADS = 64
static const double ASYNC_SLEEP_ON_WAIT = 0.01