ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

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
  • Error management
  • Forbidden processes
  • Stopping a thread
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
Starts the execution of a secondary thread. The statement is a non-locking statement: the two processes are run in parallel.
Reminder: A thread is a process run in parallel with the current application (main thread). This allows you to run a task in the background (e.g. backup, etc.).
Example
// Run a thread while passing parameters 
sDate is string 
sDate = DateSys()
// Run the thread
ThreadExécute("THREADNAME", threadNormal, "pExecQry", sDate)
// Details of the "pExecQry" procedure 
// This procedure expects a date as parameter of a query 
PROCÉDURE pExecQry(sDate)
IF HExecuteQuery(Del_Date, hQueryDefault, sDate) = False THEN
Error(HErrorInfo())
ELSE
HReadFirst(Del_Date)
END
// Compatible syntax
ThreadExécute("Thread1", threadNormal, ThreadProcedure) 
...
// Call to a global method of a class
ThreadExécute("Thread2", threadNormal, CClass::GlobalMethod)
Syntax
Universal Windows 10 AppiPhone/iPadIOS WidgetApple Watch

Declaring and executing a Thread variable Hide the details

<Result> = ThreadExecute(<WLanguage procedure> [, <Parameter 1> [... [, <Parameter N>]]] [, <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.
<Parameter 1>: Optional
Parameters that will be passed to the procedure. Caution: these parameters are passed by value (not by reference).
<Parameter N>: Optional
Parameters that will be passed to the procedure. Caution: these parameters are passed by value (not by reference).
<Options>: Optional constant
Mode for starting the thread.
threadFullCopyHFSQLContext
(Default value)
Triggers the immediate copy of the current HFSQL context.
Recommended if the thread must take into account the current positions in the files and queries of caller context.
Universal Windows 10 App This constant is not available.
threadGlobalContextForces 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.
The window context is used by default, therefore the thread is stopped when closing the window.
Remark: If ThreadExecute is used in a global initialization code (project, class or set) or from any procedure or method called from a global initialization code, this constant has no effect.
Universal Windows 10 App This constant is not available.
threadLightCopyHFSQLContextTriggers 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.
Universal Windows 10 App This constant is not available.
threadNormalStarts the thread in normal mode. The HFSQL context is copied the first time an HFSQL feature is used.
threadSecureStarts a thread in secure mode. In this mode, an exception will be thrown:
  • 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).
threadWaitForStartWaits for the actual start of the thread before continuing the execution.
Universal Windows 10 App This constant is not available.
Universal Windows 10 AppiPhone/iPadIOS WidgetApple Watch

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.
Caution: If the thread is already being executed or has already been executed, a WLanguage error will appear.

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 management functions. This name cannot correspond to an empty string ("")
<Options>: Constant
Mode for starting the thread.
threadFullCopyHFSQLContext
(Default value)
Triggers the immediate copy of the current HFSQL context.
Recommended if the thread must take into account the current positions in the files and queries of caller context.
Universal Windows 10 App This constant is not available.
threadGlobalContextForces 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.
The window context is used by default, therefore the thread is stopped when closing the window.
Remark: If ThreadExecute is used in a global initialization code (project, class or set) or from any procedure or method called from a global initialization code, this constant has no effect.
Universal Windows 10 App This constant is not available.
threadLightCopyHFSQLContextTriggers 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.
Universal Windows 10 App This constant is not available.
threadNormalStarts the thread in normal mode. The HFSQL context is copied the first time an HFSQL feature is used.
threadSecureStarts a thread in secure mode. In this mode, an exception will be thrown:
  • 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).
threadWaitForStartWaits for the actual start of the thread before continuing the execution.
Universal Windows 10 AppAndroidAndroid Widget 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. Caution: these parameters are passed by value (not by reference).
<Parameter N>: Optional
Parameters that will be passed to the procedure. Caution: 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

HFSQL contexts are automatically duplicated when ThreadExecute is executed: the number of HFSQL contexts is equal to the number of threads currently run. 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 HFSQL context management.
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 management of HFSQL errors: If several threads are used on the data files, we advise you to customize the management of HFSQL errors to avoid displaying the default windows. 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 Assisted HFSQL error handling.
  • Write operations and assignments in a thread: If values are written or assigned in a thread, the other running threads do not share this information. Some inconsistencies may occur.

Characteristics of WLanguage procedure

Caution: The calls to Info, Error, ... lock all the threads currently run.
Universal Windows 10 AppAndroidAndroid Widget The calls to Info, Error, ... do not lock the threads currently run.
Remark: The parameters passed to the procedure are passed by value and not by reference.

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.
Remark: Make sure that the threads are stopped (by ThreadState or ThreadWait) before closing the windows or destroying the objects.

Error management

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

Caution: The following processes cannot be run in the threads:
  • opening windows with WLanguage functions such as Open, Use, Close, ... 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.
Caution: UI elements (windows, controls, etc.) cannot be manipulated 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.
AndroidAndroid Widget

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:
ThreadExécute("th", threadNormal, ProcThread)
PROCEDURE ProcThread
bThreadEnVie est un booléen = Vrai
TANTQUE bThreadEnVie

// ... Traitement

// Test de la condition de fin du thread
SI <CONDITION FIN THREAD> ALORS
bThreadEnVie = Faux
FIN
FIN
Business / UI classification: Neutral code
Component: wd290vm.dll
Minimum version required
  • Version 9
This page is also available for…
Comments
Video threadExecute
https://youtu.be/IThk-OAzffA

https://windevdesenvolvimento.blogspot.com/2019/01/dicas-1996-windev-threads-02.html
amarildo
24 Jan. 2019

Last update: 09/12/2023

Send a report | Local help