THREADCREATE

Source: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgThreadCreate Last revised: 2023-04-29

Starts a user-defined procedure in a separate execution thread.

Syntax

Declare Function ThreadCreate ( _
    ByVal procptr As Sub ( ByVal userdata As Any Ptr ), _
    ByVal param As Any Ptr = 0, _
    ByVal stack_size As Integer = 0 _
) As Any Ptr

Usage:

result = ThreadCreate ( procptr [, [param] [, stack_size]] )

Parameters

• procptr — Pointer to the Sub intended to work as a thread. The sub must have this signature:

  Declare Sub myThread ( ByVal userdata As Any Ptr )

• param — Any Ptr argument passed to the thread sub's userdata parameter. Defaults to 0.
• stack_size — Optional number of bytes to reserve for this thread's stack.

Return Value

Returns an Any Ptr handle to the created thread, or 0 on failure.

Description

Starts the sub pointed to by procptr as a thread. The thread executes in parallel with the main program. The OS assigns it to a different processor if available, or time-slices on a single processor.

Execution order: There is no guarantee about the order in which threads execute or start.

Cleanup: Programs should call either ThreadWait or ThreadDetach for every created thread to release system resources.

Data exchange: To safely exchange data between threads, use mutexes (MutexCreate, MutexLock, MutexUnlock, MutexDestroy).

Stack size: stack_size changes the thread's stack from the system default. On Linux, the stack can grow beyond stack_size; on Win32 it is a fixed maximum.

Note: The userdata parameter is always mandatory in the thread sub declaration, even if unused. When unused, param can be omitted in ThreadCreate or passed as 0.

Examples

Example 1: Threading synchronization using Mutexes

Const MAX_THREADS = 10
Dim Shared As Any Ptr ttylock

Sub teletype( ByRef text As String, ByVal x As Long, ByVal y As Long )
    MutexLock ttylock
    For i As Integer = 0 To (Len(text) - 1)
        Locate x, y + i
        Print Chr(text[i])
        Sleep 25, 1
    Next
    MutexUnlock ttylock
End Sub

Sub thread( ByVal userdata As Any Ptr )
    Dim As Integer id = CInt(userdata)
    teletype "Thread (" & id & ").........", 1 + id, 1
End Sub

ttylock = MutexCreate()

Dim As Any Ptr handles(0 To MAX_THREADS-1)
For i As Integer = 0 To MAX_THREADS-1
    handles(i) = ThreadCreate(@thread, CPtr(Any Ptr, i))
    If handles(i) = 0 Then
        Print "Error creating thread:"; i
        Exit For
    End If
Next

For i As Integer = 0 To MAX_THREADS-1
    If handles(i) <> 0 Then ThreadWait(handles(i))
Next

MutexDestroy(ttylock)

Example 2: Simple thread

Sub mythread(param As Any Ptr)
    For i As Integer = 0 To 29
        Print "*";
        Sleep CInt(Rnd() * 100), 1
    Next
End Sub

Randomize(Timer())
Dim As Any Ptr thread = ThreadCreate(@mythread, 0)

For i As Integer = 0 To 29
    Print ".";
    Sleep CInt(Rnd() * 100), 1
Next

ThreadWait(thread)
Print
Sleep

Dialect Differences

• Threading is not allowed in the -lang qb dialect.

Platform Differences

• Not available in the DOS version/target of FreeBASIC (DOS does not support multithreading).
• On Linux, threads start in creation order; on Win32 this is not guaranteed.

Differences from QB

• New to FreeBASIC.

See Also

• ThreadWait
• ThreadDetach
• ThreadSelf
• MutexCreate
• MutexLock
• MutexUnlock
• MutexDestroy