{{fbdoc item="title" value="THREADCALL"}}----
Starts a user-defined procedure with parameters in a separate execution thread
	
~&//**Threadcall** uses [[ExtLibFfi|LibFFI]] internally: people who write programs using this functionality should be careful to follow ""LibFFI""'s license, which can be found at [[http://github.com/atgreen/libffi/blob/master/LICENSE]].//

{{fbdoc item="syntax"}}##
	[[KeyPgFunction|function]] **Threadcall** //subname//([//paramlist//]) [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]]
##
{{fbdoc item="usage"}}##
	//threadid// = **Threadcall** //subname//([//paramlist//])
##
{{fbdoc item="param"}}
	##//subname//##
		The name of a subroutine
	##//paramlist//##
		A list of parameters to pass to the subroutine, as with a normal sub call.	

{{fbdoc item="ret"}}
	**Threadcall** returns an ##[[KeyPgAny|any]] [[KeyPgPtr|ptr]]## handle to the thread created, or the null pointer (##0##) on failure.

{{fbdoc item="desc"}}
	Like ##[[KeyPgThreadCreate|Threadcreate]]##, **Threadcall** creates a thread which runs at the same time as the code calling it.  By placing "**Threadcall**" before almost any normal call to sub, the sub is called inside of a new thread and returns a pointer to that thread.
	
	Using **Threadcall** is simpler method of creating threads, and allows data to be passed to the thread without global variables or pointers which are not type safe.  However, ##[[KeyPgThreadCreate|Threadcreate]]## is more efficient and should be used for programs creating a large number of threads.
	
	While most subroutines are supported, the following types of subroutines may not be called:
		- Subroutines using [[KeyPgVaArg|variable arguments]].
		- Subroutines with unions which are passed as arguments.
		- Subroutines with user types containing unions, arrays, strings, or bitfields which are passed as arguments.
	
	When using **Threadcall**, parenthesis around the parameter list are required unless the subroutine has no parameters.
	
	**Warning:**
		**""-""** Presently when **Threadcall** involves to pass parameters to the thread, there is no guarantee that the corresponding data are still maintained after the end of the **Threadcall** statement and this until the thread is launched.
		**""-""** That can cause bad behavior:
			""-"" see example below where the not displayed parameter ##//id//## seems to be the consequence of a prematurely destroyed string argument (visible for a fbc version >= 1.00),
			""-"" replace ##//id As String//## with ##//id As Zstring//## in the parameters declaration seems to workaround the problem when passing this parameter.
		**""-""** Therefore it is more advisable for the moment to use ##[[KeyPgThreadCreate|Threadcreate]]## (100% safe) instead.	

{{fbdoc item="ex"}}
	{{fbdoc item="filename" value="examples/manual/threads/threadcall.bas"}}%%(freebasic)
'' Threading using "ThreadCall"

Sub thread( id As String, tlock As Any Ptr, count As Integer )
	For i As Integer = 1 To count
		MutexLock tlock
		Print "thread " & id;
		Locate , 20
		Print i & "/" & count
		MutexUnlock tlock
	Next
End Sub

Dim tlock As Any Ptr = MutexCreate()
Dim a As Any Ptr = ThreadCall thread("A", tlock, 6)
Dim b As Any Ptr = ThreadCall thread("B", tlock, 4)
ThreadWait a
ThreadWait b
MutexDestroy tlock
Print "All done (and without Dim Shared!)"
%%

{{fbdoc item="lang"}}
	- Threading is not allowed in the //[[CompilerOptlang|-lang qb]]// dialect.

{{fbdoc item="target"}}
	- **Threadcall** is not available with the DOS version / target of ""FreeBASIC"", because multithreading is not supported by DOS kernel nor the used extender.
	- In Linux the threads are always started in the order they are created, this can't be assumed in ""Win32"". It's an OS, not a ""FreeBASIC"" issue. 
	- In Linux, the ##[[KeyPgStdcall|Stdcall]]## and ##[[KeyPgPascal|Pascal]]## calling conventions are not supported
	- In Windows, the ##[[KeyPgPascal|Pascal]]## calling convention is not supported.

{{fbdoc item="diff"}}
	- New to ""FreeBASIC""

{{fbdoc item="see"}}
	- ##[[KeyPgThreadCreate|Threadcreate]]##
	- ##[[KeyPgThreadWait|Threadwait]]##
	- ##[[KeyPgMutexCreate|Mutexcreate]]##
	- ##[[KeyPgMutexLock|Mutexlock]]##
	- ##[[KeyPgMutexUnlock|Mutexunlock]]##
	- ##[[KeyPgMutexDestroy|Mutexdestroy]]##

{{fbdoc item="back" value="CatPgThreading|Threading Support Functions"}}