A basic activity signal and notification provider. More...

Inheritance diagram for Notifier:

Public Types
enum	SearchOp { SEARCH_STOP = 0 , SEARCH_CONTINUE , SEARCH_CONTINUE_WAKE }

typedef void(*	callback_type) (void , Notifier )

Public Member Functions
	Notifier (SearchOp op=SEARCH_STOP)
	Constructs a Notifier.

	Notifier (const NotifierSignal &signal, SearchOp op=SEARCH_STOP)
	Constructs a Notifier associated with a given signal.

virtual	~Notifier ()
	Destruct a Notifier.

bool	initialized () const
	Return whether the Notifier is initialized.

int	initialize (const char name, Router router)
	Initialize the associated NotifierSignal, if necessary.

const NotifierSignal &	signal () const
	Return this Notifier's associated NotifierSignal.

SearchOp	search_op () const
	Return this Notifier's search operation.

bool	active () const
	Returns whether the associated signal is active.

bool	safe_active () const
	Returns whether the associated signal is active.

bool	set_active (bool active)
	Set the associated signal's activity.

void	wake ()
	Set the associated signal to active.

void	sleep ()
	Set the associated signal to inactive.

virtual int	add_activate_callback (callback_type f, void *user_data)
	Register an activate callback with this Notifier.

virtual void	remove_activate_callback (callback_type f, void *user_data)
	Unregister an activate callback with this Notifier.

int	add_listener (Task *task)
	Register a listener with this Notifier.

void	remove_listener (Task *task)
	Unregister a listener with this Notifier.

int	add_dependent_signal (NotifierSignal *signal)
	Register a dependent signal with this Notifier.

void	remove_dependent_signal (NotifierSignal *signal)
	Unregister a dependent signal with this Notifier.

Static Public Member Functions
static NotifierSignal	upstream_empty_signal (Element *e, int port)
	Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

static NotifierSignal	upstream_empty_signal (Element e, int port, Task task)
	Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

static NotifierSignal	upstream_empty_signal (Element e, int port, Notifier dependent_notifier)
	Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

static NotifierSignal	upstream_signal (Element e, int port, Task task, const char *signal)
	Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

static NotifierSignal	upstream_empty_signal (Element e, int port, callback_type f, void user_data)
	Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

static NotifierSignal	upstream_signal (Element e, int port, callback_type f, void user_data, const char *signal)
	Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

static NotifierSignal	downstream_full_signal (Element *e, int port)
	Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

static NotifierSignal	downstream_full_signal (Element e, int port, Task task)
	Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

static NotifierSignal	downstream_full_signal (Element e, int port, Notifier dependent_notifier)
	Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

static NotifierSignal	downstream_full_signal (Element e, int port, callback_type f, void user_data)
	Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

static NotifierSignal	upstream_empty_signal (Element *e, int port, int)

static NotifierSignal	upstream_empty_signal (Element e, int port, int, Notifier )

static NotifierSignal	downstream_full_signal (Element *e, int port, int)

static NotifierSignal	downstream_full_signal (Element e, int port, int, Notifier )

Static Public Attributes
static const char	EMPTY_NOTIFIER [] = "empty"

static const char	FULL_NOTIFIER [] = "full"

Detailed Description

A basic activity signal and notification provider.

The Notifier class represents a basic activity signal associated with an element. Elements that contain a Notifier object will override Element::cast() or Element::port_cast() to return that Notifier when given the proper name. This lets other parts of the configuration find the Notifiers. See upstream_empty_signal() and downstream_full_signal().

The ActiveNotifier class, which derives from Notifier, can wake up clients when its activity signal becomes active.

Constructor & Destructor Documentation

◆ Notifier() [1/2]

Notifier::Notifier ( SearchOp op = SEARCH_STOP )

inline

Constructs a Notifier.

Parameters

op	controls notifier path search

This function constructs a Notifier object. The Notifier's associated NotifierSignal is initially idle; it becomes associated with a signal after initialize() is called.

The op argument controls path search. The rest of this entry describes it further.

Elements interested in notification generally search for Notifier objects along all possible packet paths upstream (or downstream) of one of their ports. When a Notifier is found along a path, further searching along that path is cut off, so only the closest Notifiers are found. Sometimes, however, it makes more sense to continue searching for more Notifiers. The correct behavior is Notifier-specific, and is controlled by this method. When the search encounters a Notifier, it consults the Notifier's op variable supplied to the constructor. It should equal one of three SearchOp constants, which correspond to the following behavior:

SEARCH_STOP: Stop searching along this path. This is the default.
SEARCH_CONTINUE: Continue searching along this path.
SEARCH_CONTINUE_WAKE: Continue searching along this path, but any further Notifiers should only be used for adding and removing listeners; ignore their NotifierSignal objects. This operation is useful, for example, for schedulers that store packets temporarily. Such schedulers provide their own NotifierSignal, since the scheduler may still hold a packet even when all upstream sources are empty, but since they aren't packet sources, they don't know when new packets arrive and can't wake up sleeping listeners. During initialization, such schedulers should call Notifier::upstream_empty_signal, passing their own Notifier as the fourth argument. This will ensure that their signal is turned on appropriately whenever an upstream queue becomes nonempty.

◆ Notifier() [2/2]

Notifier::Notifier	(	const NotifierSignal &	signal,
		SearchOp	op = `SEARCH_STOP`
	)

inline

Constructs a Notifier associated with a given signal.

Parameters

signal	the associated NotifierSignal
op	controls notifier path search

This function constructs a Notifier object associated with a specific NotifierSignal, such as NotifierSignal::idle_signal(). Calling initialize() on this Notifier will not change the associated NotifierSignal. The op argument is as in Notifier::Notifier(SearchOp), above.

◆ ~Notifier()

Notifier::~Notifier ( )

virtual

Destruct a Notifier.

Member Function Documentation

◆ initialized()

bool Notifier::initialized ( ) const

inline

Return whether the Notifier is initialized.

◆ initialize()

int Notifier::initialize	(	const char *	name,
		Router *	r
	)

Initialize the associated NotifierSignal, if necessary.

Parameters

name	signal name
r	associated router

Initialize the Notifier's associated NotifierSignal by calling r's Router::new_notifier_signal() method, obtaining a new basic activity signal. Does nothing if the signal is already initialized.

◆ signal()

const NotifierSignal & Notifier::signal ( ) const

inline

Return this Notifier's associated NotifierSignal.

Every Notifier object corresponds to one NotifierSignal; this method returns it. The signal is idle() before initialize() is called.

◆ search_op()

Notifier::SearchOp Notifier::search_op ( ) const

inline

Return this Notifier's search operation.

See also: Notifier() for a detailed explanation of search operations.

◆ active()

bool Notifier::active ( ) const

inline

Returns whether the associated signal is active.

Same as signal().active().

◆ safe_active()

bool Notifier::safe_active ( ) const

inline

Returns whether the associated signal is active.

Same as signal().safe_active().

◆ set_active()

bool Notifier::set_active ( bool active )

inline

Set the associated signal's activity.

Parameters

active true iff the signal should be active

Returns: previous active state

◆ wake()

void Notifier::wake ( )

inline

Set the associated signal to active.

See also: set_active

◆ sleep()

void Notifier::sleep ( )

inline

Set the associated signal to inactive.

See also: set_active

◆ add_activate_callback()

int Notifier::add_activate_callback	(	callback_type	f,
		void *	user_data
	)

virtual

Register an activate callback with this Notifier.

Parameters

f	callback function
user_data	callback data for f

Returns: 1 if notifier was added, 0 on other success, negative on error

When this Notifier's associated signal is activated, this Notifier should call f(user_data, this). Not all types of Notifier provide this functionality. The default implementation does nothing.

If f is null, then user_data is a Task pointer passed to add_listener.

See also: remove_activate_callback, add_listener, add_dependent_signal

Reimplemented in ActiveNotifier.

◆ remove_activate_callback()

void Notifier::remove_activate_callback	(	callback_type	f,
		void *	user_data
	)

virtual

Unregister an activate callback with this Notifier.

Parameters

f	callback function
user_data	callback data for f

Undoes the effect of all prior add_activate_callback(f, user_data) calls. Does nothing if (f,user_data) was never added. The default implementation does nothing.

If f is null, then user_data is a Task pointer passed to remove_listener.

See also: add_activate_callback

Reimplemented in ActiveNotifier.

◆ add_listener()

int Notifier::add_listener ( Task * task )

inline

Register a listener with this Notifier.

Parameters

task	Task to reschedule when this Notifier becomes active

When this Notifier's associated signal is activated, the Notifier should schedule task. Not all types of Notifier provide this functionality. The default implementation does nothing.

See also: remove_listener, add_activate_callback, add_dependent_signal

◆ remove_listener()

void Notifier::remove_listener ( Task * task )

inline

Unregister a listener with this Notifier.

Parameters

task	listener Task

Undoes the effect of all prior add_listener(task) calls. Does nothing if task was never added. The default implementation does nothing.

See also: add_listener

◆ add_dependent_signal()

int Notifier::add_dependent_signal ( NotifierSignal * signal )

inline

Register a dependent signal with this Notifier.

Parameters

signal dependent signal

When this Notifier's associated signal is activated, the Notifier should also activate signal. Not all types of Notifier provide this functionality. The default implementation does nothing.

See also: add_listener, add_activate_callback, remove_dependent_signal

◆ remove_dependent_signal()

void Notifier::remove_dependent_signal ( NotifierSignal * signal )

inline

Unregister a dependent signal with this Notifier.

Parameters

signal dependent signal

Undoes the effect of all prior add_dependent_signal(signal) calls. Does nothing if signal was never added. The default implementation does nothing.

See also: add_dependent_signal

◆ upstream_empty_signal() [1/4]

NotifierSignal Notifier::upstream_empty_signal	(	Element *	e,
		int	port
	)

inlinestatic

Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

Parameters

e	an element
port	the input port of e at which to start the upstream search

Searches the configuration upstream of element e's input port for empty notifiers. These notifiers are associated with packet storage, and should be true when packets are available (or likely to be available quite soon), and false when they are not. All notifiers found are combined into a single derived signal. Thus, if any of the base notifiers are active, indicating that at least one packet is available upstream, the derived signal will also be active. Element e's code generally uses the resulting signal to decide whether or not to reschedule itself.

The returned signal is generally conservative, meaning that the signal is true whenever a packet exists upstream, but the elements that provide notification are responsible for ensuring this.

Overloaded versions of this function can also register a task (as in add_listener()), a signal (as in add_dependent_notifier()), or a callback function (as in add_active_callback()) for each located notifier. When packets become available, the task will be scheduled, the signal will be activated, or the callback will be called.

Supporting upstream_empty_signal()

Elements that have an empty notifier must override the Element::cast() method. When passed the name Notifier::EMPTY_NOTIFIER, this method should return a pointer to the corresponding Notifier object.

See also: downstream_full_signal

◆ upstream_empty_signal() [2/4]

NotifierSignal Notifier::upstream_empty_signal	(	Element *	e,
		int	port,
		Task *	task
	)

inlinestatic

Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

Parameters

e	an element
port	the input port of e at which to start the upstream search
task	task to schedule when packets become available

See also: add_listener

◆ upstream_empty_signal() [3/4]

NotifierSignal Notifier::upstream_empty_signal	(	Element *	e,
		int	port,
		Notifier *	dependent_notifier
	)

inlinestatic

Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

Parameters

e	an element
port	the input port of e at which to start the upstream search
notifier	notifier to activate when packets become available

See also: add_dependent_signal

◆ upstream_signal() [1/2]

NotifierSignal Notifier::upstream_signal	(	Element *	e,
		int	port,
		Task *	task,
		const char *	signal
	)

inlinestatic

Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

Parameters

e	an element
port	the input port of e at which to start the upstream search
task	task to schedule when packets become available
signal	signal to upstream

See also: add_listener

◆ upstream_empty_signal() [4/4]

NotifierSignal Notifier::upstream_empty_signal	(	Element *	e,
		int	port,
		callback_type	f,
		void *	user_data
	)

inlinestatic

Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

Parameters

e	an element
port	the input port of e at which to start the upstream search
f	callback function
user_data	user data for callback function

See also: add_activate_callback

◆ upstream_signal() [2/2]

NotifierSignal Notifier::upstream_signal	(	Element *	e,
		int	port,
		callback_type	f,
		void *	user_data,
		const char *	sgn
	)

static

Calculate and return the NotifierSignal derived from all empty notifiers upstream of element e's input port.

Parameters

e	an element
port	the input port of e at which to start the upstream search
f	callback function
user_data	user data for callback function
signal	signal to upstream

See also: add_activate_callback

◆ downstream_full_signal() [1/4]

NotifierSignal Notifier::downstream_full_signal	(	Element *	e,
		int	port
	)

inlinestatic

Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

Parameters

e	an element
port	the output port of e at which to start the downstream search

Searches the configuration downstream of element e's output port for full notifiers. These notifiers are associated with packet storage, and should be true when there is space for at least one packet, and false when there is not. All notifiers found are combined into a single derived signal. Thus, if any of the base notifiers are active, indicating that at least one path has available space, the derived signal will also be active. Element e's code generally uses the resulting signal to decide whether or not to reschedule itself.

Overloaded versions of this function can also register a task (as in add_listener()), a signal (as in add_dependent_notifier()), or a callback function (as in add_active_callback()) for each located notifier. When space becomes available, the task will be scheduled, the signal will be activated, or the callback will be called.

In current Click, the returned signal is conservative: if it's inactive, then there is no space for packets downstream.

Supporting downstream_full_signal()

Elements that have a full notifier must override the Element::cast() method. When passed the name Notifier::FULL_NOTIFIER, this method should return a pointer to the corresponding Notifier object.

See also: upstream_empty_signal

◆ downstream_full_signal() [2/4]

NotifierSignal Notifier::downstream_full_signal	(	Element *	e,
		int	port,
		Task *	task
	)

inlinestatic

Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

Parameters

e	an element
port	the output port of e at which to start the downstream search
task	task to schedule when packets become available

See also: add_listener

◆ downstream_full_signal() [3/4]

NotifierSignal Notifier::downstream_full_signal	(	Element *	e,
		int	port,
		Notifier *	dependent_notifier
	)

inlinestatic

Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

Parameters

e	an element
port	the output port of e at which to start the downstream search
notifier	notifier to activate when packets become available

See also: add_dependent_signal

◆ downstream_full_signal() [4/4]

NotifierSignal Notifier::downstream_full_signal	(	Element *	e,
		int	port,
		callback_type	f,
		void *	user_data
	)

static

Calculate and return the NotifierSignal derived from all full notifiers downstream of element e's output port.

Parameters

e	an element
port	the output port of e at which to start the downstream search
f	callback function
user_data	user data for callback function

See also: add_activate_callback

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

include/click/notifier.hh
lib/notifier.cc

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Notifier() [1/2]

◆ Notifier() [2/2]

◆ ~Notifier()

Member Function Documentation

◆ initialized()

◆ initialize()

◆ signal()

◆ search_op()

◆ active()

◆ safe_active()

◆ set_active()

◆ wake()

◆ sleep()

◆ add_activate_callback()

◆ remove_activate_callback()

◆ add_listener()

◆ remove_listener()

◆ add_dependent_signal()

◆ remove_dependent_signal()

◆ upstream_empty_signal() [1/4]

Supporting upstream_empty_signal()

◆ upstream_empty_signal() [2/4]

◆ upstream_empty_signal() [3/4]

◆ upstream_signal() [1/2]

◆ upstream_empty_signal() [4/4]

◆ upstream_signal() [2/2]

◆ downstream_full_signal() [1/4]

Supporting downstream_full_signal()

◆ downstream_full_signal() [2/4]

◆ downstream_full_signal() [3/4]

◆ downstream_full_signal() [4/4]