Execute code in asynchronous mode¶

Asynchronous task

In some projects, it may be necessary to execute C# code in asynchronous mode, for example at regular time intervals, or at specific times, or to execute tasks that are time and/or CPU-binding without disturbing the project operation flow.

To implement this type of operation, it is necessary to create asynchronous tasks through which the desired code is executed. Q Studio provides C# class specifications that exhibit the constructors that can be used for creating asynchronous tasks.

Note

the constructors are based on the .NET framework C# System.Threading.Tasks.Task class (please see this page), which represents an asynchronous task.

The classes available are the following:

PeriodicTask to create a task that executes code at regular time intervals.
DelayedTask to create a task that executes code after a time delay.
LongRunningTask to create tasks that require significant time and/or CPU resources.

For references on constructors, see Asynchronous task constructors.

Terminating and canceling a task

A task can be terminated or canceled in runtime. When a task is terminated, it is deleted and cannot be executed again. When a task is canceled, it is stopped but it can be executed again at a later time.

Typical approach for creating, executing and terminating an asynchronous task

Please see the following example:

public override void Start()
{
    myTask = new PeriodicTask(IncrementVariable, 1000, LogicObject)
    myTask.Start();
}

public override void Stop()
{
    myTask.Dispose();
}

private void IncrementVariable()
{
    variable1.Value = variable1.Value + 1;
}

private PeriodicTask myTask;

This approach requires the following steps:

Definition of a private instance variable in the C# class contained in the NetLogic (in this example, private PeriodicTask myTask;). The class of this variable must be PeriodicTask, DelayedTask or LongRunningTask depending on the type of task to be created.
Definition of a method that the task must execute (in the example: IncrementVariable()).
Creation of the task. To do this, inside the Start() method in the C# class contained in the NetLogic, initialize the private instance variable (myTask in the example) using the class constructor (PeriodicTask in the example).

Note

the constructor requires a variety of arguments based on the class to which it belongs. See Asynchronous task constructors.
Execution of the task as soon as the NetLogic is initialized at runtime. To do this, inside the Start() method in the C# class contained in the NetLogic, invoke the Start() method on the task (myTask.Start() in the example).
Termination of the task in the Stop() method by invoking the Dispose() method.

Terminate a task

Each asynchronous task automatically terminates when the NetLogic parent node is removed. Nevertheless, as per good programming practice, it is recommended to explicitly terminate the task inside the Stop() method by invoking the Dispose() method, as shown in the following example:

public override void Stop()
{
    myTask.Dispose();
}

Warning

Invoking the Dispose() method on an asynchronous task blocks it until the code executed by the task returns the control to the caller (through control of the task state or for completion of the task).

Make a task cancelable

A task can only be canceled if the value returned from reading its IsCancellationRequested property is appropriately managed in the method that executes, usually using conditional instructions. The IsCancellationRequested property can have the following values:

false = cancellation not requested
true = cancellation requested

To use the property within the method, it is necessary to indicate the task as argument of the same method, specifying its type, as in the following example, where myTask is the task and ProcessScvFile() is the method that executes:

private void ProcessCsvFile(LongRunningTask myTask)
{
    ... // Code to execute
}

For a complete example, see LongRunningTask(action, executingNode) constructor.

Cancel a task

Invoke the Cancel() method on the task, as shown in the following example:

myTask.Cancel();

The method sets the value of the task IsCancellationRequested property to True.