INET Framework for OMNeT++/OMNEST
|
#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.
typedef std::map<int, NotifiableVector> NotificationBoard::ClientMap |
typedef std::vector<INotifiable *> NotificationBoard::NotifiableVector |
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).
Referenced by InterfaceTable::addInterface(), RoutingTable6::addOrUpdateOnLinkPrefix(), RoutingTable6::addOrUpdateOwnAdvPrefix(), RoutingTable6::addRoute(), RoutingTable::addRoute(), RSVP::announceLinkChange(), LDP::announceLinkChange(), Ieee80211MgmtSTA::beaconLost(), SnrEval::changeChannel(), AbstractRadio::changeChannel(), InterfaceTable::deleteInterface(), RoutingTable::deleteRoute(), EtherMACBase::fireChangeNotification(), Ieee80211MgmtSTA::handleAssociationResponseFrame(), EtherMAC2::handleEndTxPeriod(), SnrEval::handleLowerMsgEnd(), GilbertElliotSnr::handleLowerMsgEnd(), SnrEval::handleLowerMsgStart(), GilbertElliotSnr::handleLowerMsgStart(), PPP::handleMessage(), SnrEval::handleSelfMsg(), GilbertElliotSnr::handleSelfMsg(), SnrEval::handleUpperMsg(), SnrEval::initialize(), AbstractRadio::initialize(), InterfaceTable::interfaceChanged(), EtherMAC2::processMsgFromNetwork(), RoutingTable6::removeRoute(), AbstractRadio::setRadioState(), EtherMAC2::startFrameTransmission(), PPP::startTransmitting(), subscribe(), unsubscribe(), and BasicMobility::updatePosition().
{ 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.
{
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.
Referenced by PPP::updateHasSubcribers(), and EtherMAC2::updateHasSubcribers().
void NotificationBoard::initialize | ( | ) | [protected, virtual] |
Initialize.
{ WATCH_MAP(clientMap); }
void NotificationBoard::subscribe | ( | INotifiable * | client, |
int | category | ||
) | [virtual] |
Subscribe to changes of the given category
Referenced by RoutingTable6::initialize(), RoutingTable::initialize(), PPP::initialize(), NAMTraceWriter::initialize(), Mac80211::initialize(), LinkStateRouting::initialize(), LDP::initialize(), Ieee80211MgmtAP::initialize(), Ieee80211Mac::initialize(), Ieee80211AgentSTA::initialize(), CSMAMacLayer::initialize(), ChannelAccess::initialize(), EtherMACBase::initializeNotificationBoard(), and Ieee80211MgmtSTA::processScanCommand().
{ 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
Referenced by Ieee80211MgmtSTA::scanNextChannel(), and 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] |
{ 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] |
Referenced by fireChangeNotification(), hasSubscribers(), initialize(), subscribe(), and unsubscribe().