Counting semaphore
[Cooperative scheduler]

Semaphores are objects that can be used to manage a finite pool os resources. More...

Functions
void	BZ_SemaInit (BZ_SEMA *sema, unsigned howmany)
	Initialises a semaphore before use.
void	BZ_SemaGet (BZ_SEMA *sema, unsigned howmany)
	Get the given number of objects from a semaphore.
int	BZ_SemaTry (BZ_SEMA *sema, unsigned howmany)
	Tries to get the given number of objects from a semaphore.
void	BZ_SemaPut (BZ_SEMA *sema, unsigned howmany)
	Return resources to a semaphore.

---

Detailed Description

Semaphores are objects that can be used to manage a finite pool os resources.

They hold a count of resources that are available in the pool. Threads can ask for a given number of resources and get suspended if the request can not be satisfied. Threads holding resources can return them to the pool when they are not used any more; the returned resources can be then given out to threads waiting for them.

The semaphore code is very short but rather unsophisticated. If you use a lot of semaphores and many threads suspended on them, then you will use a lot of CPU rather unnecessarily. Do not use semaphores as general purpose synchronisation mechanism; try to use the event system, which is much more efficient.

---

Function Documentation

void BZ_SemaGet	(	BZ_SEMA *	sema,
		unsigned	howmany
	)

Get the given number of objects from a semaphore.

This function takes the requested number of objects from the semaphore. If there are not enough objects, it will suspend the caller until the necessary amount of objects are delivered by one or more BZ_SemaPut() calls.

Parameters:

	sema	Pointer to the semaphore
	howmany	The number of resources to get

Attention:

This function must not be called from an interrupt. It you do that, the system will crash.

void BZ_SemaInit	(	BZ_SEMA *	sema,
		unsigned	howmany
	)

Initialises a semaphore before use.

Parameters:

	sema	Pointer to the semaphore to initialise
	howmany	The initial value of the semaphore

void BZ_SemaPut	(	BZ_SEMA *	sema,
		unsigned	howmany
	)

Return resources to a semaphore.

The function adds resources to a semaphore. The resource count is a 32-bit unsigned number and is not protected against overflow. The function does not suspend the caller and is safe to call from an interrupt routine.

Parameters:

	sema	Pointer to the semaphore
	howmany	The number of resources to put to the semaphore

int BZ_SemaTry	(	BZ_SEMA *	sema,
		unsigned	howmany
	)

Tries to get the given number of objects from a semaphore.

The function checks if the given semaphore holds as many objects as requested. If yes, then it takes the given number and returns, reporting success. If the semaphore does not have onogh resources, then the function leaves the semaphore unchanged and returns immediately, reporting failure. This function never suspends the caller and is safe to call from an interrupt routine.

Parameters:

	sema	Pointer to the semaphore
	howmany	The number of resources to get

Return values:

	1	Success, the requested amount of resources were taken
	0	Failure, the semaphore does not have enough resources