# 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