HALFRED  0.4.0
Typedefs | Functions
OSNotifier interface

Detailed Description


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.


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)

Typedef Documentation

typedef struct OSNotifierDesc* OSNotifier

OSNotifier type.

Function Documentation

OSNotifier OSNTF_Create ( int  count)

Creates a new instance of OSNotifier.

new OSNotifier
void OSNTF_Destroy ( OSNotifier  notifier)

Releases a previously created instance of an OSNotifier.

notifiernotifier to release
OSNotifier OSNTF_Lock ( int  count)

Locks a notifier in the built-in pool.

locked notifier
void OSNTF_Unlock ( OSNotifier  notifier)

Unlocks and releases a notifier back to the built-in pool.

notifierto 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).

countnumber of events to "tick away"
resulting count of the notifier after decrementing.
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.

0 if the notification occurred before timeout and 1 if timeout occurred.