xHarbour Reference Documentation > Function Reference

StartThread()

Starts a new thread.

Syntax

StartThread( <bBlock>|<cFuncName>|<pFuncPtr> ;
           [,<xParams,...>] ) --> pThreadHandle
or

StartThread( <oObject>, <cMethodName>|<pMethodPtr> ;
           [,<xParams,...>] ) --> pThreadHandle

Arguments

<bBlock>

This is a code block to be executed in the new thread.

<cFuncName>

This is a character string holding the symbolic name of a function or procedure to be executed in the new thread.

<pFuncPtr>

Instead o a function orprocedure name, the pointer to a function or procedure can be specified. It can be obtained using function HB_FuncPtr().

<oObject>

If the first parameter is an object (Valtype()=="O"), the second parameter specifies the method to execute in the new thread.

<cMethodName>

This is a character string holding the symbolic name of the method of <oObject> to be executed.

<pMethodPrt>

This is a pointer to the method to be executed. It can be obtained using function HB_ObjMsgPtr().

<xParams,...>

An optional, comma separated list of values to be passed as parameters to a code block, function, procedure or method can be specified with <xParams,...>.

Return

The function returns a handle to the started thread.

Description

StartThread() is the only function in xHarbour that creates a new thread, and assigns to it the program code to be executed in the new thread. An application begins execution always with one thread, the Main thread, from where new threads can be spawned. When an application uses multiple threads, the program code specified for a particular thread runs parallel with program code assigned to other threads. The simultaneous execution of program code in multiple threads is the task of the operating system which grants CPU access for different threads on its own behalf.

Function StartThread() assigns the program code to execute in a new thread to the operating system. This can be a function, procedure, code block or the method of an object. These possibilities are covered by the parameters accepted by StartThread(). In addition, all values specified with <xParams,...> are passed on to the routine defined for the new thread when the operating system starts with thread execution.

When StartThread() returns, the new thread may or may not have started to execute the assigned routine. StartThread() merely guarantees that all memory resources are set up for the operating system to run the new thread. Unless an error occurs, the function returns a handle to the new thread. This Thread handle must be preserved for use with other multi-threading functions. The Thread handle is valid as long as the operating systeme executes the thread, i.e. as long as the thread is running. The Thread handle becomes invalid when the operating system terminates the thread. Function IsValidThread() is available to test if a thread is still running.

Notes on Multi-threaded programming

A detailed description of "Threads" and "Multi-threaded programming" goes way beyond the scope of this documentation. There are many books available on this topic and many free online resources inform about them (see www.wikipedia.org for a start)

A programmer has absolutely no control about WHEN the operating system starts or ends a thread, or WHEN it grants a thread access to the CPU. This fact of parallel program execution rises concurrency issues when two threads access the same memory resources, like a STATIC variable, for example. The value of a STATIC variable is not guaranteed when two threads change its value simultaneously. The thread that had last access to a STATIC variable, determines its value.

Concurrency issues for memory resources that may arise in multi-threaded programming can be resolved be means of Mutexes. A Mutex can be locked and freed by one thread. A thread that holds a lock on a Mutex blocks execution of other threads, thus preventing them from accessing the memory recources protected by the Mutex while it is locked. See function HB_MutexCreate() for more information on Mutexes.

Info

See also:	GetCurrentThread(), GetThreadID(), HB_MutexCreate(), HB_OpenProcess(), IsValidThread(), JoinThread(), StopThread(), ThreadSleep()
Category:	Multi-threading functions , xHarbour extensions
Source:	vm\thread.c
LIB:	xhbmt.lib
DLL:	xhbmtdll.dll

Example

// The example uses a thread to display the time in the
// upper right corner of the screen while function Browse()
// is active. The thread is suspended for one second with
// ThreadSleep().

   PROCEDURE Main
      LOCAL pThread

      CLS
      USE Customer
      pThread := StartThread( "ShowTime", 0, MaxCol()-7 )

      Browse()

      StopThread( pThread )

      WaitForThreads()
   RETURN


   PROCEDURE ShowTime( nRow, nCol )
      DO WHILE .T.
         DispOutAt( nRow, nCol, Time() )
         ThreadSleep( 1000 )
      ENDDO
   RETURN