|
HALFRED
0.4.0
|
Introduction.
The OSNotifier in HAL provides a simple notification mechanism, based on OSSem interface available in the OS module. This mechanism is used internally by the IO module in I/O operations that require timeout.
The idea behind the notifier is to alert an OS thread when a specified number of events has happened. For example, the notifier may alert that a number of bytes were received through a communication port.
The notification is based on a semaphore. The threads that wants to wait for the notification first sets up a notifier, either by calling OSNTF_Create or OSNTF_Lock, and then waits for it using OSNTF_Wait. Under the hood the thread actually waits for a semaphore with a given timeout. Other threads or interrupt service routines signal events by calling the OSNTF_Tick. Each "tick" decrements the notifier counter until a specified amount of events happen. When counter reaches zero the semaphore is given and the waiting thread is unblocked. The thread is then responsible for cleaning up the notifier, by calling either OSNTF_Destroy or OSNTF_Unlock depending how the notifier was created.
The OSNotifier implementation is completely OS and hardware independent, relying only on OSSem interface.
Notifier pool.
This module also manages a pool of notifiers. This pool is used internally by IO module in I/O operations that require timeout. The HAL_OS_NOTIFIER_POOL_SIZE definition in HAL configuration file controls the size of the pool. The pool API consists of just two functions OSNTF_Lock and OSNTF_Unlock.
Using notifiers.
In order to use a notifier the application must first obtain it, by either calling the OSNTF_Create function, that allocates a new notifier in heap memory (see HEAP module) or by calling OSNTF_Lock which locks and returns a notifier from a pool. Both calls also set up the initial counter of the notifier. HAL internally uses only the second method (the pool).
When a notifier is obtained the calling thread may already call OSNTF_Wait to block until a specified count of events happen or timeout occurs. these events are signaled in another thread or interrupt service routine by a call to OSNTF_Tick. Each call to OSNTF_Tick may signal one or more than one event (the "count" parameter).
When a notifier is no longer needed it should be destroyed by a call to OSNTF_Destroy or released back to the pool by a call to OSNTF_Unlock.
Typedefs | |
| typedef struct OSNotifierDesc * | OSNotifier |
Functions | |
| OSNotifier | OSNTF_Create (int count) |
| void | OSNTF_Destroy (OSNotifier notifier) |
| OSNotifier | OSNTF_Lock (int count) |
| void | OSNTF_Unlock (OSNotifier notifier) |
| int | OSNTF_Tick (OSNotifier notifier, int count) |
| int | OSNTF_Wait (OSNotifier notifier, OSTime timeout) |
| typedef struct OSNotifierDesc* OSNotifier |
OSNotifier type.
| OSNotifier OSNTF_Create | ( | int | count | ) |
Creates a new instance of OSNotifier.
| count |
| void OSNTF_Destroy | ( | OSNotifier | notifier | ) |
Releases a previously created instance of an OSNotifier.
| notifier | notifier to release |
| OSNotifier OSNTF_Lock | ( | int | count | ) |
Locks a notifier in the built-in pool.
| void OSNTF_Unlock | ( | OSNotifier | notifier | ) |
Unlocks and releases a notifier back to the built-in pool.
| notifier | to unlock |
| int OSNTF_Tick | ( | OSNotifier | notifier, |
| int | count | ||
| ) |
Decrements the notifier by a given count. Returns current notfier count. If the return value is 0 or less it means that the notifier was activated (notification was issued).
| notifier | notifier |
| count | number of events to "tick away" |
| int OSNTF_Wait | ( | OSNotifier | notifier, |
| OSTime | timeout | ||
| ) |
Halts current task waiting for notification. Returns 0 if the notification occurred before timeout, and 1 if timeout occurred.
| notifier | |
| timeout |
1.8.7