Skip to content

About threading in HALCON Scriptđź”—

HALCON supports several levels of parallel execution. Depending on your application, you can rely on one of the following:

  1. Automatic operator parallelization inside the HALCON library. For more information, see Automatic parallelization.

  2. Threads created within the HALCON Script language via thread_start (known as par_start in HDevelop). This aspect is described below.

  3. 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.

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_start is 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 when thread_join is 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_join where 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_join and 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 containing thread_start.
    “Step into” creates the thread and moves into it, allowing you to step through the thread. The thread containing thread_start is 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_start statement using “edit and continue”, make sure that the program counter is positioned before thread_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_start are initially ignored. Calling thread_join for the affected thread raises the exception. Multiple threads can call thread_join for the same thread. Each call raises the same exception.