{{fbdoc item="title" value="MUTEXLOCK"}}----
Acquires a mutex

{{fbdoc item="syntax"}}##
	[[KeyPgDeclare declare]] [[KeyPgSub sub]] **Mutexlock** ( [[KeyPgByval byval]] //id// [[KeyPgAs as]] [[KeyPgAny any]] [[KeyPgPtr ptr]] )
##
{{fbdoc item="usage"}}##
	**Mutexlock**( //id// )
##
{{fbdoc item="param"}}
	##//id//##
		The ##[[KeyPgAny any]] [[KeyPgPtr ptr]]## handle of the mutex to be locked.

{{fbdoc item="desc"}}
	##Mutexlock## halts any other threads using a mutex "handle", generated by ##[[KeyPgMutexCreate Mutexcreate]]##, until the handle is unlocked with ##[[KeyPgMutexUnlock Mutexunlock]]##.

	See ##[[KeyPgMutexCreate Mutexcreate]]## for more general information on mutexes.

{{fbdoc item="ex"}}
	See also the examples in ##[[KeyPgMutexCreate Mutexcreate]]## and also ##[[KeyPgThreadCreate Threadcreate]]##.

{{fbdoc item="filename" value="examples/manual/threads/mutexlock.bas"}}%%(freebasic)
'Example of mutual exclusion for synchronization between 2 threads
'by using 2 Mutexes only (by self lock and mutual unlock):
'The Producer works one time, then the Consumer works one time.
'
'Principle of synchronisation by mutual exclusion
'(initial condition: mut#A and mut#B locked)
'
'          Thread#A              XORs              Thread#B
'Do_something#A_with_exclusion          MutexLock(mut#A)
'MutexUnlock(mut#A)                       Do_something#B_with_exclusion
'.....                                  MutexUnlock(mut#B)
'MutexLock(mut#B)                       .....

'----------------------------------------------------------------------

Dim Shared produced As Any Ptr
Dim Shared consumed As Any Ptr
Dim consumer_id As Any Ptr
Dim producer_id As Any Ptr


Sub consumer ( ByVal param As Any Ptr )
	For i As Integer = 0 To 9
	    MutexLock produced
	    Print , ",consumer gets:" ; i
	    MutexUnlock consumed
	    Sleep 5
	Next i
End Sub

Sub producer ( ByVal param As Any Ptr )
	For i As Integer = 0 To 9
	    Print "Producer puts:" ; i;
	    MutexUnlock produced
	    MutexLock consumed
	Sleep 5
Next i
End Sub


produced = MutexCreate
consumed = MutexCreate
If ( produced = 0 ) Or ( consumed = 0 ) Then
	Print "Error creating mutexes! Exiting..."
	Sleep
	End
End If

MutexLock produced
MutexLock consumed

consumer_id = ThreadCreate ( @ consumer )
producer_id = ThreadCreate ( @ producer )
If ( producer_id = 0 ) Or ( consumer_id = 0 ) Then
	Print "Error creating threads! Exiting..."
	Sleep
	End
End If

ThreadWait consumer_id
ThreadWait producer_id

MutexDestroy consumed
MutexDestroy produced

Sleep
%%

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

{{fbdoc item="target"}}
	- The DOS version of ""FreeBASIC"" does not allow for threads, as the OS does not support them.
	- 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. 

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

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

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