|typedef struct OSNotifierDesc *||OSNotifier|
|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)|
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.
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_config controls the size of the pool. The pool API consists of just two functions OSNTF_Lock and OSNTF_Unlock.
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).
|typedef struct OSNotifierDesc* OSNotifier|
Creates a new instance of OSNotifier.
- new OSNotifier
Releases a previously created instance of an OSNotifier.
notifier notifier to release
Locks a notifier in the built-in pool.
- locked notifier
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"
- resulting count of the notifier after decrementing.
Unlocks and releases a notifier back to the built-in pool.
notifier to unlock
Halts current task waiting for notification. Returns 0 if the notification occurred before timeout, and 1 if timeout occurred.
- 0 if the notification occurred before timeout and 1 if timeout occurred.
Generated on Thu Feb 22 2018 13:14:55 for RCM API C++ Library by 18.104.22.168