ThreadExecute (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

This content has been translated automatically. Click here to view the French version.

Help / WLanguage / WLanguage functions / Standard functions / Process functions / Threads, semaphores, signals and mutex

Characteristics of a thread created in WLanguage
Thread and HFSQL
Characteristics of WLanguage procedure
Lifecycle of a thread
Handling errors
Forbidden processes
Stopping a thread

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

ThreadExecute (Function)

In french: ThreadExecute

Starts the execution of a secondary thread. The instruction is non-blocking: the two processes run in parallel.

Reminder A thread is a process launched in parallel with the current application ("main thread"). This allows you to run a task in the background (e.g. backup, etc.).

New in version 2025

Syntaxes for manipulating a Thread variable are now available.

Secure threads (constant threadSécurisé) are now available.

Example

// Exécution d'un thread avec passage de paramètres 
sDate is string 
sDate = DateSys()
// Exécution du thread
ThreadExecute("THREADNAME", threadNormal, "pExecReq", (sDate))
// ---------------------------------------------------------
// Détail de la procédure "pExecReq" 
// Cette procédure attend une date en paramètre d'une requête 
PROCEDURE pExecReq(sDate)
IF HExecuteQuery(Sup_Date, hQueryDefault, sDate) = False THEN
	Error(HErrorInfo())
ELSE
	HReadFirst(Sup_Date)
END

// Syntaxe compatible
ThreadExecute("Thread1", threadNormal, ProcédureThread) 
...
// Appel d'une méthode globale d'une classe
ThreadExecute("Thread2", threadNormal, CClasse::MéthodeGlobale)

Syntax

Declaring and executing a Thread variable Hide the details

<Result> = ThreadExecute(<WLanguage procedure> [, <Parameters>] [, <Options>])

<Result>: Thread variable

Thread variable corresponding to the thread executed.

<WLanguage procedure>: Procedure name

Name of the WLanguage procedure run. This procedure is run in parallel with the application.

<Parameters>: List of values enclosed in brackets, separated by commas

Parameters of the procedure to be executed. This list of parameters has the following format:
(<Parameter 1>, ..., <Parameter N>)
where:
<Parameter 1> is the first parameter of the procedure.
...
<Parameter N> is the nth parameter of the procedure.
Warning Parameters are passed by value. In the case of variables of complex types (arrays, object), the value is the element itself.. To restrict access to this variable, you can:
make a copy of the variable (with the LOCAL keyword),
use critical sections (with CriticalSectionStart (Function) or the <critical section> attribute)

<Options>: Optional constant

Thread start mode.
threadFullCopyHFSQLContext
(Default value) Triggers the immediate copy of the current HFSQL context.
Recommended if the thread needs to take into account the current positions in the files and queries of the caller's context.
threadGlobalContext Forces the use of the global context of the project if the thread is run from a window. The thread will continue to run until the application is closed.
By default, the window context is used, so the thread is stopped when the window is closed.
Note: If the ThreadExecute function is used in a global initialization code (project, class or collection) or from any procedure or method called from a global initialization code, this constant has no effect.
threadLightCopyHFSQLContext Triggers the immediate copy of a part of the current HFSQL context.
Only the directories containing the data files in HFSQL Classic mode and/or the connections in HFSQL Client/Server mode are stored.
threadNormal Starts the thread in normal mode. The HFSQL context is copied the first time an HFSQL feature is used.
threadSecure Starts a thread in secure mode. In this mode:
a compilation error will occur if the controls are accessed in the thread.
an exception will be raised:
if the thread accesses the controls at runtime,
if the ThreadStop function is called.
when the window that triggered the thread is closed, a request to stop the thread is generated (but the thread continues to run after the window is closed).
threadWaitForStart Waits for the actual start of the thread before continuing the execution.
This constant is not available.

Executing a thread already described (Thread variable) Hide the details

<Result> = ThreadExecute(<Thread>)

<Result>: Thread variable

Thread variable corresponding to the thread executed.

<Thread>: Thread variable

Name of the Thread variable corresponding to the thread to execute.
This thread is a secure thread, which implies the following:
a compilation error will occur if the controls are accessed in the thread.
an exception will be raised:
if the thread accesses the controls at runtime,
if the ThreadStop function is called.
when the window that triggered the thread is closed, a request to stop the thread is generated (but the thread continues to run after the window is closed).
Warning: If the thread is already running or has already been executed, a WLanguage error will be triggered.

Executing a thread by naming it (Compatible syntax) Hide the details

ThreadExecute(<Thread name> , <Options> , <WLanguage procedure> [, <Parameter 1> [... [, <Parameter N>]]])

<Thread name>: Character string

Name that will be given to the thread. This name will be used by all thread functions. It cannot correspond to an empty string ("")

<Options>: Constant

Thread start mode.
threadFullCopyHFSQLContext
(Default value) Triggers the immediate copy of the current HFSQL context.
Recommended if the thread needs to take into account the current positions in the files and queries of the caller's context.
threadGlobalContext Forces the use of the global context of the project if the thread is run from a window. The thread will continue to run until the application is closed.
By default, the window context is used, so the thread is stopped when the window is closed.
Note: If the ThreadExecute function is used in a global initialization code (project, class or collection) or from any procedure or method called from a global initialization code, this constant has no effect.
threadLightCopyHFSQLContext Triggers the immediate copy of a part of the current HFSQL context.
Only the directories containing the data files in HFSQL Classic mode and/or the connections in HFSQL Client/Server mode are stored.
threadNormal Starts the thread in normal mode. The HFSQL context is copied the first time an HFSQL feature is used.
threadSecure Starts a thread in secure mode. In this mode:
a compilation error will occur if the controls are accessed in the thread.
an exception will be raised:
if the thread accesses the controls at runtime,
if the ThreadStop function is called.
when the window that triggered the thread is closed, a request to stop the thread is generated (but the thread continues to run after the window is closed).
threadWaitForStart Waits for the actual start of the thread before continuing the execution.
This constant is not available.

<WLanguage procedure>: Procedure name

Name of the WLanguage procedure run. This procedure is run in parallel with the application.

<Parameter 1>: Optional

Parameters that will be passed to the procedure. Please note: these parameters are passed by value (not by reference).

<Parameter N>: Optional

Parameters that will be passed to the procedure. Please note: these parameters are passed by value (not by reference).

Remarks

Characteristics of a thread created in WLanguage

A thread created in WLanguage can only be a procedure or a class method. The thread cannot correspond to a WLanguage process (code of a control for example).

If the thread is a class method, ThreadExecute must be run from one of the processes of the class (constructor or method).

Thread and HFSQL

When executing the ThreadExecute FUNCTIONfunction, HFSQL contexts are automatically duplicated: there are as many HFSQL contexts as there are threads running. The entire HFSQL context is copied (filter, search condition, etc.). The HFSQL context evolves independently in each thread.

This allows you, for example, to perform two different iterations on the same data file in two different threads.

Two methods can be used to copy HFSQL contexts:

Full copy of context (by default)
Light copy of context.

For more details on how HFSQL contexts are copied and their limits (depending on the database used), see Managing HFSQL contexts.

Example:

A filter is created on the Customer data file.
ThreadExecute is called to create the CTX2 thread.
The Customer data file is filtered in each thread (main and CTX2). The filter will still be enabled in the CTX2 thread even if the filter is disabled in the main thread.

Special cases:

Assisted HFSQL error handling If several threads are used on data files, it is advisable to customize HFSQL error handling so that the default windows are not displayed. To do so, use HOnError to disable the automatic management of errors or to redirect the management of errors to a custom procedure (without displaying windows). For more details, see HFSQL error handling help.
Writes and assigns in a thread If writes or assigns are performed in a thread, other running threads do not share this information. Some inconsistencies may occur.

Characteristics of WLanguage procedure

Warning Calls to functions Info, Error, ... block all running threads.

Calls to functions Info, Error, ... do not block running threads.

Note Parameters passed to the procedure are passed by value, not by reference.

For more details on how to open a window from a secondary thread, see Opening a window in a secondary thread.

Lifecycle of a thread

The thread is automatically stopped at the end of the execution of the WLanguage procedure started by ThreadExecute.

The thread is also stopped in the following cases:

if ThreadExecute is called from the code of a window, the thread will be stopped when the window is closed.
if ThreadExecute is called from a global process (initialization, explicit call in the main context), the thread will be stopped when the application is terminated.
if ThreadExecute is called in a class method, the thread is stopped when the object is destroyed.

To force the execution of the thread in the main context, use the threadGlobalContext constant.

To force the thread to stop, use ThreadStop. This function can be used to stop a thread from the main thread.

Note It is advisable to check that threads have been stopped (using functions ThreadState or ThreadWait) before closing windows or destroying objects.

Handling errors

A fatal error occurs in the following cases:

if the procedure does not exist.
if a thread with the same name is currently running.

Forbidden processes

Please note: the following processes cannot be run in threads:

opening windows with WLanguage functions such as Open, Use, Close, etc. A specific management mode must be implemented if some windows must be handled in threads (rare case). For more details, see Opening a window in a secondary thread.
managing events.
multitask.
managing timers.

Warning: it is forbidden to manipulate the UI (windows, fields, etc.) in a secondary thread.
When a secondary thread must interact with the user or update the UI, it must use a process started from the main thread. This process can correspond to:

a global procedure of the project or a local procedure (of a window, etc.) called by ExecuteMainThread,
the "Request for refreshing the display" event of a window run by RequestRefreshUI.

Stopping a thread

ThreadStop is not available in Android.

Only the thread itself must stop thread, at the end of the WLanguage procedure called by ThreadExecute.

Example:

ThreadExecute("th", threadNormal, ProcThread)

PROCEDURE ProcThread
bThreadAlive is boolean = True
WHILE bThreadAlive

//... Process

// Test the end condition of the thread
IF <THREAD END CONDITION> THEN
bThreadAlive = False
END
END

Business / UI classification: Neutral code

Component: wd300vm.dll