//
//------------------ DOK FILE --------------------------------------------------
+Header	systemLib
=pkg	bios
=title	System
=short	memory, apps, threads, lock, join, await
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- Lock
+Proto	Lock
=type	Lock
=mode	structure
=pkg	bios
=impl	mcy
=link	
=desc	This is the type for a Lock structure. It allows to make sure that only one thread at a time evaluates a specific function.
//
//
//------------------ PROTO ----------------------------------------------------- lockSync
+Proto	lockSync
=type	fun Lock (fun -> a1) -> a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function makes sure that the lambda function fCompute is evaluated by a single thread at a time.
When a thread B calls this lambda function with the same lock while another thread A is already in, the thread B is suspended until the thread A has completed evaluation of fCompute.
//
+arg	lck
=type	Lock
=desc	A lock
//
+arg	fCompute
=type	fun -> a1
=desc	A lambda expression without argument and any result
//
+arg	result
=type	a1
=desc	The result of the lambda function
//
//
//------------------ PROTO ----------------------------------------------------- lockCreate
+Proto	lockCreate
=type	fun -> Lock
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function creates a new [[Lock]]. It is ready to be used with [[lockSync]].
//
+arg	result
=type	Lock
=desc	A new lock
//
//
//------------------ PROTO ----------------------------------------------------- Join
+Proto	Join
=type	Join{a1}
=mode	structure
=pkg	bios
=impl	mcy
=link	
=desc
This is the type for a Join structure. This structure allows a thread to wait until another thread sends a result.
-	a thread A creates a join structure with the [[joinCreate]] function
-	it starts a thread B
-	then the thread A calls [[joinWait]]: this suspends the thread A
-	the thread B does a computation and sends the result R with the [[joinSend]] function
-	this resumes the execution of thread A, with the result R of the thread B
//
//
//------------------ PROTO ----------------------------------------------------- joinCreate
+Proto	joinCreate
=type	fun -> Join{a1}
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function creates a join structure.
//
+arg	result
=type	Join{a1}
=desc	A Join structure
//
//
//------------------ PROTO ----------------------------------------------------- joinSend
+Proto	joinSend
=type	fun Join{a1} a1 -> a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function sends an element to a [[Join]] structure. It will resume the thread waiting for this element with the [[joinWait]] function.
//
+arg	join
=type	Join{a1}
=desc	A Join structure of any type
//
+arg	element
=type	a1
=desc	An element of the same type
//
+arg	result
=type	a1
=desc	The element
//
//
//------------------ PROTO ----------------------------------------------------- joinWait
+Proto	joinWait
=type	fun Join{a1} -> a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function suspends the thread until a result is available from the [[Join]] structure.
When the [[Join]] structure contains already a result, there is no suspension of the thread.
//
+arg	join
=type	Join{a1}
=desc	A Join structure of any type
//
+arg	result
=type	a1
=desc	A parameter of the same type
//
//
//------------------ PROTO ----------------------------------------------------- thisThread
+Proto	thisThread
=type	fun -> Thread
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the current thread.
//
+arg	result
=type	Thread
=desc	A thread
//
//
//------------------ PROTO ----------------------------------------------------- threadOrigin
+Proto	threadOrigin
=type	fun Thread -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns the full name of the function which created the thread th.
The full name is a concatenation of the package name and the function name.
	> threadOrigin (thread);;
>-> Str: "boot.run"
//
+arg	th
=type	Thread
=desc	A thread
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- threadCycles
+Proto	threadCycles
=type	fun Thread -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the number of cycles of the thread. It is the number of bytecode operations since the start of the thread.
//
+arg	th
=type	Thread
=desc	A thread
//
+arg	result
=type	Int
=desc	A positive integer
//
//
//------------------ PROTO ----------------------------------------------------- threadStart
+Proto	threadStart
=type	fun Str (fun -> a1) -> Thread
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function starts a new thread and specifies its name and the lambda function fStart to evaluate first on this new thread.
The existing thread shares its memory limit with the new thread.
//
+arg	name
=type	Str
=desc	A string
//
+arg	fStart
=type	fun -> a1
=desc	A lambda function without parameter and any result
//
+arg	result
=type	Thread
=desc	A thread
//
//
//------------------ PROTO ----------------------------------------------------- threadId
+Proto	threadId
=type	fun Thread -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the unique id of thread th.
//
+arg	th
=type	Thread
=desc	A thread
//
+arg	result
=type	Int
=desc	An integer
//
//
//------------------ PROTO ----------------------------------------------------- threadName
+Proto	threadName
=type	fun Thread -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the name associated to a thread. See threadStart.
//
+arg	th
=type	Thread
=desc	A thread
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- threadPost
+Proto	threadPost
=type	fun Thread (fun -> a1) -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function posts a message to another thread or itself.
The message is a lambda function without parameter. Processing the message means evaluating the lambda function.
The thread th will evaluate the lambda function. Therefore the memory allocated for this evaluation will be count on the thread th memory quota.
This function may suspend the origin thread when there are too many messages in the queue of thread th. The thread will resume as soon as the thread th computes enough messages.
//
+arg	th
=type	Thread
=desc	A thread
//
+arg	task
=type	fun -> a1
=desc	A lambda function with no parameter and any result
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- threadStop
+Proto	threadStop
=type	fun Thread -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function stops the thread th.
//
+arg	th
=type	Thread
=desc	A thread
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- threadT0
+Proto	threadT0
=type	fun Thread -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the timestamp at the start of the thread.
//
+arg	th
=type	Thread
=desc	A thread
//
+arg	result
=type	Int
=desc	A timestamp in seconds
//
//
//------------------ PROTO ----------------------------------------------------- exit
+Proto	exit
=type	fun -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function stops the execution of the current thread.
The typechecker considers that the result is a boolean, however it is never returned.
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- Thread
+Proto	Thread
=type	Thread
=mode	structure
=pkg	bios
=impl	mcy
=link	
=desc	The type for threads.
//
//
//------------------ PROTO ----------------------------------------------------- appStart
+Proto	appStart
=type	fun Lock (fun -> Bool) Str (fun -> a1) -> a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function will create a new App after checking for concurrent start.
-	it enters the lock
-	it calls fIsStarted and aborts the operation when fIsStarted returns true
-	then it creates a new thread with the name and the max memory maxMem
-	eventually it starts the new thread with function fStart
-	the appStart function returns the result of fStart
//
+arg	lock
=type	Lock
=desc	A Lock or nil
//
+arg	fIsStarted
=type	fun -> Bool
=desc	A lambda function with no parameter and a boolean result
//
+arg	name
=type	Str
=desc	A string
//
+arg	fStart
=type	fun -> a1
=desc	A lambda function without parameter and any result
//
+arg	result
=type	a1
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- await
+Proto	await
=type	fun (fun Join{a1} -> a2) -> a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function allows to convert an asynchronous function into a synchronous function.
//
+arg	asyncFun
=type	fun Join{a1} -> a2
=desc	A lambda function with a lambda function as a parameter and any result
//
+arg	result
=type	a1
=desc	An element
//
//
//------------------ PROTO ----------------------------------------------------- kill
+Proto	kill
=type	fun Int -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function stops the thread specified by its unique Id.
//
+arg	id
=type	Int
=desc	An thread Id
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- args
+Proto	args
=type	fun -> list Str
=mode	function
=pkg	bios
=impl	native
=link	
=desc	This function returns the list of arguments when Minimacy is called from the command line.
//
+arg	result
=type	list Str
=desc	A list of strings
//
//
//------------------ PROTO ----------------------------------------------------- device
+Proto	device
=type	Str
=mode	constant
=pkg	bios
=impl	native
=link	
=desc
This constant is a device name.
	> device
>-> Str: "windows"
Values are: unix, macos, ios, windows
//
//
//------------------ PROTO ----------------------------------------------------- version
+Proto	version
=type	Str
=mode	constant
=pkg	bios
=impl	native
=link	explicit
=desc
This constant is the version number.
	> version
>-> Str: "1.2.0"
//------------------ PROTO ----------------------------------------------------- niceStop
+Proto	niceStop
=type	fun -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- hardStop
+Proto	hardStop
=type	fun -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
//
+arg	result
=type	Bool
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- setHostUser
+Proto	setHostUser
=type	fun Str -> Bool
=mode	Function
=pkg	bios
=impl	native
=link	
=desc	
This function works only on Unix-like systems, it changes the current user. It is useful when the virtual machine must be launched with root permissions, for example to open a tcp server on port 80, and quickly switch to a lower priority user account.
Returns:
- nil: the function has no effect on this host
- true: ok
- false: nok
//
+arg	userName
=type	Str
=desc	a user name
//
+arg	result
=type	Bool
=desc	true, false or nil
//
//
//------------------ PROTO ----------------------------------------------------- randomEntropy
+Proto	randomEntropy
=type	fun Int -> Int
=mode	Function
=pkg	bios
=impl	native
=link	
=desc
This function adds entropy to the pseudo-random generator. It has no effect when a hardware random generator is available on the host. See [[randomHardware]].
//
+arg	value
=type	Int
=desc	any integer value
//
+arg	result
=type	Int
=desc	the unchanged value
//
//
//------------------ PROTO ----------------------------------------------------- randomHardware
+Proto	randomHardware
=type	fun -> Bool
=mode	Function
=pkg	bios
=impl	native
=link	
=desc	
This function returns true when a hardware random generator is available on the host.
//
+arg	result
=type	Bool
=desc	true or false
//
//
//------------------ PROTO ----------------------------------------------------- setError
+Proto	setError
=type	fun Error -> Error
=mode	Function
=pkg	bios
=impl	native
=link	
=desc	
This function attaches an error to the current [[Thread]].
It can be retrieved with [[lastError]].
//
+arg	error
=type	Error
=desc	
//
+arg	result
=type	Error
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- lastError
+Proto	lastError
=type	fun -> Error
=mode	Function
=pkg	bios
=impl	native
=link	
=desc	
This function retrieves and clear the error attached to the current [[Thread]] with [[setError]].
//
+arg	result
=type	Error
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- gcTrace
+Proto	gcTrace
=type	fun Bool -> Bool
=mode	Function
=pkg	bios
=impl	native
=link	
=desc	
//
+arg	A
=type	Bool
=desc	
//
+arg	result
=type	Bool
=desc