About threading in HALCON Scriptđź”—
HALCON supports several levels of parallel execution. Depending on your application, you can rely on one of the following:
-
Automatic operator parallelization inside the HALCON library. For more information, see Automatic parallelization.
-
Threads created within the HALCON Script language via
thread_start(known aspar_startin HDevelop). This aspect is described below. -
Threads created in the final user application, for example C++ or C#, making calls via HALCON Script Engine or HALCON language interfaces. For more information, see Parallel programming using HALCON.
HALCON offers a number of operators and data types that are especially useful for HALCON Script threading, such as message queues, mutexes, conditions, and barriers.
More Info
See also Tutorial: Parallelization concepts.
HALCON Script allows you to create and execute multiple threads within a program. Threads are represented by thread handles. Use thread_create to create a thread handle, thread_start to create and start a thread, and thread_join to wait for one or more threads to finish.
Syntax and basic operationđź”—
-
thread_create (out tuple thread_handle)
Creates a thread handle. -
thread_start (tuple thread_handle, <procedure_call>)- Creates and starts a thread executing the procedure call bound to the given thread handle.
- Using just an operator call in
thread_startis not supported. Wrap the call by a procedure. - The procedure call syntax is identical to making a normal procedure call.
- Input parameters are passed to the procedure immediately.
- Output parameters are bound to the specified output expressions and will be written on
thread_join.
Supported output expressions are:
- Variables (control and iconic)
- Dictionary items
Example
proc test_proc(out tuple X) endproc thread_start(T, test_proc(MyVar)) thread_start(T, test_proc(Dict.key)) -
thread_join (tuple thread_handle)
Waits for one or more threads to finish. Output of joined threads parameters are written to the specified output expressions whenthread_joinis called.Example
thread_join([T1, T2])
Lifetimes and scopesđź”—
A thread remains valid as long as it is referenced by a thread handle. A started thread continues to run until it reaches the end, encounters an exception, or is no longer referenced by a thread handle. A thread can be detached to keep running even after the last handle reference is discarded:
Example
thread_set_param(T, 'detached', 'true')
A thread handle can be passed as parameter to a different procedure or returned to the caller.
Other threads can wait on the thread using thread_join but they will not get return values since these were bound to the original calling scope.
Multiple parallel or subsequent calls to thread_join are allowed. Only the first one actually needs to wait.
A thread handle can be returned as HTuple to an HALCON Script Engine host application and passed to other procedures running in the same HALCON Script Engine.
Note
-
There is no automatic join of started subthreads when the main execution finishes. Use explicit
thread_joinwhere needed. -
A thread handle cannot be used in a different instance of HALCON Script Engine.
Early Adopter restriction
At the moment, a thread handle cannot be reused to start another thread after the associated thread has finished.
Debugging threaded programsđź”—
The following rules apply when debugging a threaded program:
- Pausing and continuing
-
When execution is paused, all threads are paused. Individual thread suspension is not supported. A thread finishes its current statement before pausing. A pending
thread_joinand any interruptible operators are then cancelled.Note
Cancelling an interruptible operator affects all interruptible HALCON operators running in the same process. Therefore, pausing one parallel HALCON Script execution may affect another execution running in the same HDevelopEVO instance.
- Stepping behavior
-
thread_start
“Step over” creates the thread and stops it before executing the first statement. Execution then continues in the thread containingthread_start.
“Step into” creates the thread and moves into it, allowing you to step through the thread. The thread containingthread_startis paused in the meantime.
-
thread_join
“Step over” waits for all threads whose handles are in the statement to finish.
“Step into” waits for the first thread and then pauses. The next step waits for the next thread.
- Breakpoints and exceptions
- If one thread reaches a breakpoint, a stop, or an exception, all threads are paused. The thread causing the stop is selected as active, and the stop reason is displayed in the thread view.
- Jump to cursor
- Jump to cursor moves the program counter for the currently selected thread.
- Thread view
- Selecting a thread displays its call stack, variables, and current source position.
- Restart
- Restarting execution terminates and removes all threads.
- Edit and continue
- The “edit and continue” functionality is supported for threads. The procedure currently executed by a thread can be edited and execution can then be continued.
- Edit and continue with
thread_start - When restarting a
thread_startstatement using “edit and continue”, make sure that the program counter is positioned beforethread_create. Otherwise, you may get an exception for attempting to start the same thread twice.
Exceptionsđź”—
- During debugging
- If a thread encounters an unhandled exception, execution is paused and the location of the error is displayed.
- Without debugging
-
Note
This applies when using Run > Start Without Debugging in HDevelopEVO or when using the HALCON Script Engine.
- Unhandled exceptions in threads started with
thread_startare initially ignored. Callingthread_joinfor the affected thread raises the exception. Multiple threads can callthread_joinfor the same thread. Each call raises the same exception.