Docs

You are here:
OSNotifier interface

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)
 

Detailed Description

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_config 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 Documentation

typedef struct OSNotifierDesc* OSNotifier

OSNotifier type.

Function Documentation

OSNotifier OSNTF_Create ( int  count)

Creates a new instance of OSNotifier.

Parameters
count
Returns
new OSNotifier
void OSNTF_Destroy ( OSNotifier  notifier)

Releases a previously created instance of an OSNotifier.

Parameters
notifiernotifier to release
OSNotifier OSNTF_Lock ( int  count)

Locks a notifier in the built-in pool.

Returns
locked notifier
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).

Parameters
notifiernotifier
countnumber of events to "tick away"
Returns
resulting count of the notifier after decrementing.
void OSNTF_Unlock ( OSNotifier  notifier)

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

Parameters
notifierto unlock
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.

Parameters
notifier
timeout
Returns
0 if the notification occurred before timeout and 1 if timeout occurred.
Go to Top