//
//------------------ DOK FILE --------------------------------------------------
+Header	fifoLib
=pkg	bios
=title	Fifos
=short	first in, first out
=desc	Fifos are a convenient tool for many algorithms even if they bring side-effects.
//
//
//------------------ PROTO ----------------------------------------------------- fifoFromList
+Proto	fifoFromList
=type	fun list a1 -> fifo a1
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns a fifo containing the elements of the list src.
//
+arg	src
=type	list a1
=desc	A list of any type
//
+arg	result
=type	fifo a1
=desc	A fifo of the same type
//
//
//------------------ PROTO ----------------------------------------------------- fifo
+Proto	fifo
=type	fifo a1
=mode	type
=pkg	language
=impl	mcy
=link	
=desc
fifo stands for "first in, first out". It is like a unidirectional pipe: elements are introduced at one side and comes out the other end.
There is no syntaxic way to create a fifo with a content. Usually a fifo is created empty, but you can create a fifo from a list:
	> fifoFromList (1:2::3::nil)
>-> fifo Int: #3
>   Int: 1 (0x1)
>   Int: 2 (0x2)
>   Int: 3 (0x3)
//
//
//------------------ PROTO ----------------------------------------------------- fifoCount
+Proto	fifoCount
=type	fun fifo a1 -> Int
=mode	function
=pkg	bios
=impl	native
=link	
=desc
This function returns the number of elements currently in the fifo, or nil if src is nil.
	> let fifoFromList (1::2::3::nil) -> fifo in fifoCount (fifo)
>-> Int: 3 (0x3)
//
+arg	src
=type	fifo a1
=desc	A fifo of any type
//
+arg	result
=type	Int
=desc	The number of elements in the fifo
//
//
//------------------ PROTO ----------------------------------------------------- fifoCreate
+Proto	fifoCreate
=type	fun -> fifo a1
=mode	function
=pkg	bios
=impl	native
=link	
=desc	This function creates a new empty fifo.
//
+arg	result
=type	fifo a1
=desc	A new fifo
//
//
//------------------ PROTO ----------------------------------------------------- fifoIn
+Proto	fifoIn
=type	fun fifo a1 a1 -> fifo a1
=mode	function
=pkg	bios
=impl	native
=link	
=desc
This function is a side-effect: it pushes an element into a fifo, and returns the same fifo.
	> let fifoFromList (1::2::3::nil) -> fifo in fifoIn (fifo, 4);;
>-> fifo Int: #4
>   Int: 1 (0x1)
>   Int: 2 (0x2)
>   Int: 3 (0x3)
>   Int: 4 (0x4)
//
+arg	src
=type	fifo a1
=desc	A fifo of any type
//
+arg	element
=type	a1
=desc	An element of the same type
//
+arg	result
=type	fifo a1
=desc	The same fifo
//
//
//------------------ PROTO ----------------------------------------------------- fifoList
+Proto	fifoList
=type	fun fifo a1 -> list a1
=mode	function
=pkg	bios
=impl	native
=link	
=desc
This function returns the list of the elements currently in the fifo. The first element of this list is the next to come out.
In order to prevent this list to be altered later, the fifo is emptied.
	> let fifoFromList (1::2::3::nil) -> fifo in fifoList (fifo)
>-> list Int:
>   Int: 1 (0x1)
>   Int: 2 (0x2)
>   Int: 3 (0x3)
//
+arg	src
=type	fifo a1
=desc	A fifo of any type
//
+arg	result
=type	list a1
=desc	The list of the elements currently in the fifo
//
//
//------------------ PROTO ----------------------------------------------------- fifoNext
+Proto	fifoNext
=type	fun fifo a1 -> a1
=mode	function
=pkg	bios
=impl	native
=link	
=desc
This function returns the next element to come out, but this element remains in the fifo src.
	> let fifoFromList (1::2::3::nil) -> fifo in fifoNext (fifo)
>-> Int: 1 (0x1)
//
+arg	src
=type	fifo a1
=desc	A fifo of any type
//
+arg	result
=type	a1
=desc	The next element to come out
//
//
//------------------ PROTO ----------------------------------------------------- fifoOut
+Proto	fifoOut
=type	fun fifo a1 -> a1
=mode	function
=pkg	bios
=impl	native
=link	
=desc
This function returns the next element to come out, and removes it from the fifo src.
	> let fifoFromList (1::2::3::nil) -> fifo in fifoOut (fifo)
>-> Int: 1 (0x1)
//
+arg	A
=type	fifo a1
=desc	A fifo of any type
//
+arg	result
=type	a1
=desc	The next element to come out