#include <NotificationBoard.h>
Public Types | |
| typedef std::vector < INotifiable * > | NotifiableVector |
| typedef std::map< int, NotifiableVector > | ClientMap |
Public Member Functions | |
Methods for consumers of change notifications | |
| virtual void | subscribe (INotifiable *client, int category) |
| virtual void | unsubscribe (INotifiable *client, int category) |
| virtual bool | hasSubscribers (int category) |
Methods for producers of change notifications | |
| virtual void | fireChangeNotification (int category, const cPolymorphic *details=NULL) |
Protected Member Functions | |
| virtual void | initialize () |
| virtual void | handleMessage (cMessage *msg) |
Protected Attributes | |
| ClientMap | clientMap |
Friends | |
| std::ostream & | operator<< (std::ostream &, const NotifiableVector &) |
Acts as a intermediary between module where state changes can occur and modules which are interested in learning about those changes; "Notification Broker".
Notification events are grouped into "categories." Examples of categories are: NF_HOSTPOSITION_UPDATED, NF_RADIOSTATE_CHANGED, NF_PP_TX_BEGIN, NF_PP_TX_END, NF_IPv4_ROUTE_ADDED, NF_BEACON_LOST NF_NODE_FAILURE, NF_NODE_RECOVERY, etc. Each category is identified by an integer (right now it's assigned in the source code via an enum, in the future we'll convert to dynamic category registration).
To trigger a notification, the client must obtain a pointer to the NotificationBoard of the given host or router (explained later), and call its fireChangeNotification() method. The notification will be delivered to all subscribed clients immediately, inside the fireChangeNotification() call.
Clients that wish to receive notifications should implement (subclass from) the INotifiable interface, obtain a pointer to the NotificationBoard, and subscribe to the categories they are interested in by calling the subscribe() method of the NotificationBoard. Notifications will be delivered to the receiveChangeNotification() method of the client (redefined from INotifiable).
In cases when the category itself (an int) does not carry enough information about the notification event, one can pass additional information in a data class. There is no restriction on what the data class may contain, except that it has to be subclassed from cPolymorphic, and of course producers and consumers of notifications should agree on its contents. If no extra info is needed, one can pass a NULL pointer in the fireChangeNotification() method.
A module which implements INotifiable looks like this:
class Foo : public cSimpleModule, public INotifiable { ... virtual void receiveChangeNotification(int category, const cPolymorphic *details) {..} ... };
Obtaining a pointer to the NotificationBoard module of that host/router:
NotificationBoard *nb; // this is best made a module class member nb = NotificationBoardAccess().get(); // best done in initialize()
See NED file for additional info.
Definition at line 85 of file NotificationBoard.h.
| typedef std::map<int, NotifiableVector> NotificationBoard::ClientMap |
Definition at line 89 of file NotificationBoard.h.
| typedef std::vector<INotifiable *> NotificationBoard::NotifiableVector |
Definition at line 88 of file NotificationBoard.h.
| void NotificationBoard::fireChangeNotification | ( | int | category, | |
| const cPolymorphic * | details = NULL | |||
| ) | [virtual] |
Tells NotificationBoard that a change of the given category has taken place. The optional details object may carry more specific information about the change (e.g. exact location, specific attribute that changed, old value, new value, etc).
Definition at line 96 of file NotificationBoard.cc.
Referenced by InterfaceTable::addInterface(), RoutingTable6::addOrUpdateOnLinkPrefix(), RoutingTable6::addOrUpdateOwnAdvPrefix(), RoutingTable6::addRoute(), RoutingTable::addRoute(), RSVP::announceLinkChange(), LDP::announceLinkChange(), InterfaceTable::deleteInterface(), RoutingTable::deleteRoute(), EtherMACBase::fireChangeNotification(), EtherMAC2::handleEndTxPeriod(), PPP::handleMessage(), InterfaceTable::interfaceChanged(), EtherMAC2::processMsgFromNetwork(), RoutingTable6::removeRoute(), EtherMAC2::startFrameTransmission(), PPP::startTransmitting(), subscribe(), and unsubscribe().
{
Enter_Method("fireChangeNotification(%s, %s)", notificationCategoryName(category),
details?details->info().c_str() : "n/a");
ClientMap::iterator it = clientMap.find(category);
if (it==clientMap.end())
return;
NotifiableVector& clients = it->second;
for (NotifiableVector::iterator j=clients.begin(); j!=clients.end(); j++)
(*j)->receiveChangeNotification(category, details);
}
| void NotificationBoard::handleMessage | ( | cMessage * | msg | ) | [protected, virtual] |
Does nothing.
Definition at line 55 of file NotificationBoard.cc.
{
error("NotificationBoard doesn't handle messages, it can be accessed via direct method calls");
}
| bool NotificationBoard::hasSubscribers | ( | int | category | ) | [virtual] |
Returns true if any client has subscribed to the given category. This, by using a local boolean 'hasSubscriber' flag, allows performance-critical clients to leave out calls to fireChangeNotification() if there's no one subscribed anyway. The flag should be refreshed on each NF_SUBSCRIBERLIST_CHANGED notification.
Definition at line 90 of file NotificationBoard.cc.
Referenced by PPP::updateHasSubcribers(), and EtherMAC2::updateHasSubcribers().
| void NotificationBoard::initialize | ( | ) | [protected, virtual] |
| void NotificationBoard::subscribe | ( | INotifiable * | client, | |
| int | category | |||
| ) | [virtual] |
Subscribe to changes of the given category
Definition at line 61 of file NotificationBoard.cc.
Referenced by RoutingTable6::initialize(), RoutingTable::initialize(), PPP::initialize(), NAMTraceWriter::initialize(), LinkStateRouting::initialize(), LDP::initialize(), and EtherMACBase::initializeNotificationBoard().
{
Enter_Method("subscribe(%s)", notificationCategoryName(category));
// find or create entry for this category
NotifiableVector& clients = clientMap[category];
// add client if not already there
if (std::find(clients.begin(), clients.end(), client) == clients.end())
clients.push_back(client);
fireChangeNotification(NF_SUBSCRIBERLIST_CHANGED, NULL);
}
| void NotificationBoard::unsubscribe | ( | INotifiable * | client, | |
| int | category | |||
| ) | [virtual] |
Unsubscribe from changes of the given category
Definition at line 75 of file NotificationBoard.cc.
Referenced by PPP::~PPP().
{
Enter_Method("unsubscribe(%s)", notificationCategoryName(category));
// find (or create) entry for this category
NotifiableVector& clients = clientMap[category];
// remove client if there
NotifiableVector::iterator it = std::find(clients.begin(), clients.end(), client);
if (it!=clients.end())
clients.erase(it);
fireChangeNotification(NF_SUBSCRIBERLIST_CHANGED, NULL);
}
| std::ostream& operator<< | ( | std::ostream & | os, | |
| const NotifiableVector & | v | |||
| ) | [friend] |
Definition at line 25 of file NotificationBoard.cc.
{
os << v.size() << " client(s)";
for (unsigned int i=0; i<v.size(); i++)
{
os << (i==0 ? ": " : ", ");
if (dynamic_cast<cModule*>(v[i]))
{
cModule *mod = dynamic_cast<cModule*>(v[i]);
os << "mod (" << mod->getClassName() << ")" << mod->getFullName() << " id=" << mod->getId();
}
else if (dynamic_cast<cPolymorphic*>(v[i]))
{
cPolymorphic *obj = dynamic_cast<cPolymorphic*>(v[i]);
os << "a " << obj->getClassName();
}
else
{
os << "a " << opp_typename(typeid(v[i]));
}
}
return os;
}
ClientMap NotificationBoard::clientMap [protected] |
Definition at line 93 of file NotificationBoard.h.
Referenced by fireChangeNotification(), hasSubscribers(), initialize(), subscribe(), and unsubscribe().
1.7.1