Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Related Pages

s3_periodic_notifier Class Reference

Instantiate one of these to periodically signal an event using a semaphore. More...

#include <s3_periodic_notifier.h>

Collaboration diagram for s3_periodic_notifier:

Public Types
typedef unsigned int	period_t
	Type of the period. More...
Public Methods
	s3_periodic_notifier (period_t n_period_ms=1)
	Default and initialising constructor. More...
	~s3_periodic_notifier ()
	Destructor. More...
void	enable ()
	Enable notification. More...
void	disable ()
	Disable notification. More...
void	set_period (period_t n_period_ms)
	Set the period to `n_period` milliseconds. More...
void	subscribe (s3_semaphore &sem)
	Subscribe the supplied semaphore to the `notification_list`. More...
void	unsubscribe (s3_semaphore &sem)
	Unsubscribe the supplied semaphore to the `notification_list`. More...
Protected Methods
bool	is_subscribed (s3_semaphore &sem)
	Return whether the specified semaphore is already in the notification list. More...
void *	main_loop (void *)
	Main event loop. More...
void	notify ()
	Notify all subscribers. More...
Protected Attributes
period_t	period_ms
	Notification period in milliseconds. More...
bool	enabled
	Enabled flag. More...
std::list< s3_semaphore * >	notification_list
	List of semaphores to be notified. More...
s3_mutex	state_lock
	Mutex to lock critical sections. More...
Static Protected Attributes
event_loop *	ev_loop = 0
	Event loop instance shared by everyone. More...
s3_mutex	ev_loop_lock
	Shared mutex protecting ev_loop. More...
Friends
class	event_loop

Detailed Description

Instantiate one of these to periodically signal an event using a semaphore.

Each instance has an associated period and a list of semaphores. Every time a the interval timer expires, each semaphore is post() 'ed, thereby notifying all processes wait() 'ing on it.

The notifier can also be disabled, which suspends notification until it is enabled again. This should not be used as an accurate timer. It is implemented in a thread-safe way.

Attributes:

period: The interval between successive notifications. It is specified in milliseconds, but is only accurate to within 50 ms.
enabled: Flag indicating whether an instance performs notification or is suspended.
notification_list: A list of s3_semaphore.

Methods:

enable: Set enabled to true.
disable: Set enabled to false.
set_period: Set the period to the specified number of milliseconds.
subscribe: Subscribe a semaphore by adding it to the notification list. If it is already subscribed, this call fails.
unsubscribe: Unsubscribe a semaphore by removing it from the notification list. If if is not subscribed, this call fails.

Operation:

If enabled is true, each semaphore in notification_list is notified periodically by performing a post() on each. The time between successive notifications is equal to period.
If enabled is false, the semaphores are not notified.
After the notifier is enabled, the first notification takes place after a maximum interval of period and successive notifications are period apart.

Definition at line 86 of file s3_periodic_notifier.h.

Member Typedef Documentation

typedef unsigned int s3_periodic_notifier::period_t

Type of the period.

Definition at line 92 of file s3_periodic_notifier.h.
Referenced by s3_periodic_notifier, and s3_periodic_notifier::event_loop::set_period.

Constructor & Destructor Documentation

s3_periodic_notifier::s3_periodic_notifier ( period_t n_period_ms = 1 )

Default and initialising constructor.
Instantiate with supplied period. Use default period when invoked as default constructor. The notifier starts out disabled and with an empty notification list.
Parameters:

n_period_ms Period in milliseconds (optional: default = 0).

Definition at line 236 of file s3_periodic_notifier.cc.
References s3_periodic_notifier::event_loop::add_client, enabled, ev_loop, ev_loop_lock, event_loop, s3_mutex::lock, period_ms, period_t, s3_periodic_notifier::event_loop::set_period, and s3_mutex::unlock.

s3_periodic_notifier::~s3_periodic_notifier ( )

Destructor.
Remove from event loop and destruct event loop if no clients left.
Definition at line 252 of file s3_periodic_notifier.cc.
References s3_periodic_notifier::event_loop::clients, ev_loop, ev_loop_lock, s3_mutex::lock, s3_periodic_notifier::event_loop::remove_client, and s3_mutex::unlock.

Member Function Documentation

void s3_periodic_notifier::disable ( )

Disable notification.

Definition at line 274 of file s3_periodic_notifier.cc.
References enabled, s3_mutex::lock, state_lock, and s3_mutex::unlock.
Referenced by s3_txport_tcp_rx_task::cleanup, s3_txport_tcp_tx_task::cleanup, s3_txport_local::cleanup, s3_post_office_switch::main_loop, and s3_post_office::main_loop.

void s3_periodic_notifier::enable ( )

Enable notification.

Definition at line 266 of file s3_periodic_notifier.cc.
References enabled, s3_mutex::lock, state_lock, and s3_mutex::unlock.
Referenced by s3_txport_tcp_rx_task::main_loop, s3_txport_tcp_tx_task::main_loop, s3_txport_local::main_loop, s3_post_office_switch::main_loop, and s3_post_office::main_loop.

bool s3_periodic_notifier::is_subscribed ( s3_semaphore & sem ) [protected]

Return whether the specified semaphore is already in the notification list.

Note:
This should only be called while state_lock is held.

Definition at line 348 of file s3_periodic_notifier.cc.
References notification_list.
Referenced by subscribe, and unsubscribe.

void* s3_periodic_notifier::main_loop ( void * ) [protected]

Main event loop.
Currently one per notifier, which implies one thread per notifier: crude, but effective (and fairly efficient). Numerous proposals have been sumbitted to change the structure, so that there is only a single timer thread that is shared by a number of notifiers. It is not currently implemented in the dumb way because the clever way requires

void s3_periodic_notifier::notify ( ) [protected]

Notify all subscribers.
This is called when the event timer has figured out that it is notification time. This call does nothing if we are not enabled.
Definition at line 331 of file s3_periodic_notifier.cc.
References s3_mutex::lock, notification_list, state_lock, and s3_mutex::unlock.

void s3_periodic_notifier::set_period ( period_t n_period_ms )

Set the period to n_period milliseconds.

Definition at line 282 of file s3_periodic_notifier.cc.
References ev_loop, s3_mutex::lock, period_ms, s3_periodic_notifier::event_loop::set_period, state_lock, and s3_mutex::unlock.
Referenced by s3_txport_tcp_tx_task::s3_txport_tcp_tx_task.

void s3_periodic_notifier::subscribe ( s3_semaphore & sem )

Subscribe the supplied semaphore to the notification_list.

Precondition:
subscribe(sem) has not been called before.

Definition at line 291 of file s3_periodic_notifier.cc.
References is_subscribed, s3_mutex::lock, notification_list, state_lock, and s3_mutex::unlock.
Referenced by s3_txport_local::main_loop, s3_post_office_switch::main_loop, s3_post_office::main_loop, s3_txport_tcp_rx_task::s3_txport_tcp_rx_task, and s3_txport_tcp_tx_task::s3_txport_tcp_tx_task.

void s3_periodic_notifier::unsubscribe ( s3_semaphore & sem )

Unsubscribe the supplied semaphore to the notification_list.

Precondition:
subscribe(sem) has been called.

Definition at line 310 of file s3_periodic_notifier.cc.
References is_subscribed, s3_mutex::lock, notification_list, state_lock, and s3_mutex::unlock.
Referenced by s3_txport_local::cleanup, s3_post_office_switch::main_loop, s3_post_office::main_loop, s3_txport_tcp_rx_task::~s3_txport_tcp_rx_task, and s3_txport_tcp_tx_task< s3_message, s3_socket_tcp >::~s3_txport_tcp_tx_task.

Friends And Related Function Documentation

friend class event_loop [friend]

Definition at line 129 of file s3_periodic_notifier.h.
Referenced by s3_periodic_notifier.

Member Data Documentation

bool s3_periodic_notifier::enabled [protected]

Enabled flag.

Definition at line 147 of file s3_periodic_notifier.h.
Referenced by disable, enable, and s3_periodic_notifier.

s3_periodic_notifier::event_loop * s3_periodic_notifier::ev_loop = 0 [static, protected]

Event loop instance shared by everyone.
event_loop is instantiated by the first notifier and deleted by the last one.
Definition at line 46 of file s3_periodic_notifier.cc.
Referenced by s3_periodic_notifier, set_period, and ~s3_periodic_notifier.

s3_mutex s3_periodic_notifier::ev_loop_lock [static, protected]

Shared mutex protecting ev_loop.

Definition at line 47 of file s3_periodic_notifier.cc.
Referenced by s3_periodic_notifier, and ~s3_periodic_notifier.

std::list<s3_semaphore*> s3_periodic_notifier::notification_list [protected]

List of semaphores to be notified.

Definition at line 151 of file s3_periodic_notifier.h.
Referenced by is_subscribed, notify, subscribe, and unsubscribe.

period_t s3_periodic_notifier::period_ms [protected]

Notification period in milliseconds.

Definition at line 143 of file s3_periodic_notifier.h.
Referenced by s3_periodic_notifier, and set_period.

s3_mutex s3_periodic_notifier::state_lock [protected]

Mutex to lock critical sections.

Definition at line 155 of file s3_periodic_notifier.h.
Referenced by disable, enable, notify, set_period, subscribe, and unsubscribe.

The documentation for this class was generated from the following files:

Send comments to: s3fc@stonethree.com

s3_periodic_notifier Class Reference

Public Types

Public Methods

Protected Methods

Protected Attributes