inet::ScenarioManager Class Reference

Scenario Manager (experimental) which executes a script specified in XML. More...

#include <ScenarioManager.h>

Inheritance diagram for inet::ScenarioManager:

Public Member Functions
	ScenarioManager ()
Public Member Functions inherited from inet::LifecycleController
	LifecycleController ()
virtual	~LifecycleController ()
virtual bool	initiateOperation (LifecycleOperation *operation, IDoneCallback *completionCallback=nullptr)
	Initiate an operation. More...

Protected Types
typedef std::pair< cGate *, cGate * >	GatePair

Protected Member Functions
cModule *	getRequiredModule (const char *path)
cModule *	getRequiredModule (const cXMLElement *node, const char *attr)
cGate *	findMandatorySingleGateTowards (cModule *srcModule, cModule *destModule)
GatePair	getConnection (const cXMLElement *node)
void	setChannelParam (cGate *srcGate, const char *name, const char *value)
void	disconnect (cGate *srcGate)
void	createConnection (const cXMLElementList &paramList, cChannelType *channelType, cGate *srcGate, cGate *destGate)
virtual void	processCommand (const cXMLElement *node)
virtual void	processAtCommand (const cXMLElement *node)
virtual void	processSetParamCommand (const cXMLElement *node)
virtual void	processSetChannelParamCommand (const cXMLElement *node)
virtual void	processCreateModuleCommand (const cXMLElement *node)
virtual void	processDeleteModuleCommand (const cXMLElement *node)
virtual void	processConnectCommand (const cXMLElement *node)
virtual void	processDisconnectCommand (const cXMLElement *node)
virtual void	processModuleSpecificCommand (const cXMLElement *node)
virtual void	processLifecycleCommand (const cXMLElement *node)
virtual void	initialize () override
virtual void	handleMessage (cMessage *msg) override
virtual void	refreshDisplay () const override
Protected Member Functions inherited from inet::LifecycleController
virtual bool	resumeOperation (LifecycleOperation *operation)
virtual void	doOneStage (LifecycleOperation *operation, cModule *submodule)
virtual void	moduleOperationStageCompleted (Callback *callback)

Protected Attributes
int	numChanges = 0
int	numDone = 0
Protected Attributes inherited from inet::LifecycleController
Callback *	spareCallback = nullptr

Detailed Description

Scenario Manager (experimental) which executes a script specified in XML.

ScenarioManager has a few built-in commands such as <set-param>, <set-channel-param>, etc, and can pass commands to modules that implement the IScriptable interface. The <at> built-in command can be used to group commands to be carried out at the same simulation time.

See NED file for details.

See also

IScriptable

Member Typedef Documentation

GatePair

typedef std::pair<cGate *, cGate *> inet::ScenarioManager::GatePair

protected

Constructor & Destructor Documentation

ScenarioManager()

inet::ScenarioManager::ScenarioManager ( )

inline

{}

Member Function Documentation

createConnection()

void inet::ScenarioManager::createConnection ( const cXMLElementList &  paramList, cChannelType *  channelType, cGate *  srcGate, cGate *  destGate  )

protected

{
    if (!channelType)
        srcGate->connectTo(destGate);
    else {
        cChannel *channel = channelType->create("channel");
 
        // set parameters:
        for (auto child : paramList) {
            const char *name = xmlutils::getMandatoryFilledAttribute(*child, ATTR_NAME);
            const char *value = xmlutils::getMandatoryAttribute(*child, ATTR_VALUE);
            channel->par(name).parse(value);
        }
 
        // connect:
        srcGate->connectTo(destGate, channel);
    }
}

Referenced by processConnectCommand().

disconnect()

void inet::ScenarioManager::disconnect ( cGate *  srcGate )

protected

{
    srcGate->disconnect();
}

Referenced by processDisconnectCommand().

findMandatorySingleGateTowards()

cGate * inet::ScenarioManager::findMandatorySingleGateTowards ( cModule *  srcModule, cModule *  destModule  )

protected

{
    cGate *resultGate = nullptr;
    for (cModule::GateIterator it(srcModule); !it.end(); ++it) {
        cGate *gate = *it;
        if (gate->getType() == cGate::OUTPUT && gate->getNextGate() != nullptr && gate->getNextGate()->getOwnerModule() == destModule) {
            if (resultGate)
                throw cRuntimeError("Ambiguous gate: there is more than one connection between the source and destination modules");
            resultGate = gate;
        }
    }
    if (!resultGate)
        throw cRuntimeError("No such gate: there is no connection between the source and destination modules");
    return resultGate;
}

Referenced by getConnection().

getConnection()

ScenarioManager::GatePair inet::ScenarioManager::getConnection ( const cXMLElement *  node )

protected

{
    // Connection can be identifier with the source module plus either the source gate or the
    // destination module. The connection must be within a single level of the module hierarchy,
    // i.e. the two modules must be siblings. With the latter option, there must be exactly
    // one connection between the two modules. If the specified gate or connection identifies
    // bidirectional connection (inout gates and '<-->' notation in NED), the source gates
    // of both directions are returned.
    //
    if (node->getAttribute(ATTR_SRC_GATE)) {
        cModule *srcModule = getRequiredModule(node, ATTR_SRC_MODULE);
        const char *srcGateSpec = xmlutils::getMandatoryFilledAttribute(*node, ATTR_SRC_GATE);
        std::string name;
        int index;
        parseIndexedName(srcGateSpec, name, index);
        if (srcModule->gateType(name.c_str()) == cGate::OUTPUT) {
            return GatePair(srcModule->gate(name.c_str(), index), nullptr); // throws if not found
        }
        else if (srcModule->gateType(name.c_str()) == cGate::INOUT) {
            cGate *outputHalf = srcModule->gateHalf(name.c_str(), cGate::OUTPUT, index);
            cGate *inputHalf = srcModule->gateHalf(name.c_str(), cGate::INPUT, index);
            if (outputHalf->getNextGate() == nullptr || inputHalf->getPreviousGate() == nullptr)
                throw cRuntimeError("The specified gate (or the input or output half of it) is not connected");
            if (outputHalf->getNextGate()->getOwnerModule() != inputHalf->getPreviousGate()->getOwnerModule())
                throw cRuntimeError("The specified gate (or the input or output half of it) is connected to a node on another level");
            return GatePair(outputHalf, inputHalf->getPreviousGate());
        }
        else {
            throw cRuntimeError("'src-gate' must be an inout or output gate");
        }
    }
    else if (node->getAttribute(ATTR_DEST_MODULE)) {
        cModule *srcModule = getRequiredModule(node, ATTR_SRC_MODULE);
        cModule *destModule = getRequiredModule(node, ATTR_DEST_MODULE);
        if (srcModule->getParentModule() != destModule->getParentModule())
            throw cRuntimeError("Source and destination modules must be under the same parent");
        cGate *srcGate = findMandatorySingleGateTowards(srcModule, destModule);
        bool bidir = strlen(srcGate->getNameSuffix()) > 0; // TODO use =srcGate->isGateHalf();
        if (!bidir) {
            return GatePair(srcGate, nullptr);
        }
        else {
            cGate *otherHalf = srcModule->gateHalf(srcGate->getBaseName(), cGate::INPUT, srcGate->isVector() ? srcGate->getIndex() : -1); // TODO use =srcGate->getOtherHalf();
            cGate *otherSrcGate = otherHalf->getPreviousGate();
            if (otherSrcGate == nullptr)
                throw cRuntimeError("Broken bidirectional connection: the corresponding input gate is not connected");
            if (otherSrcGate->getOwnerModule() != destModule)
                throw cRuntimeError("Broken bidirectional connection: the input and output gates are connected to two different modules");
            return GatePair(srcGate, otherSrcGate);
        }
    }
    else {
        throw cRuntimeError("Missing attribute: Either 'src-gate' or 'dest-module' must be present");
    }
}

Referenced by processDisconnectCommand(), and processSetChannelParamCommand().

getRequiredModule() [1/2]

cModule * inet::ScenarioManager::getRequiredModule ( const char *  path )

protected

{
    cModule *mod = getModuleByPath(path);
    if (!mod)
        throw cRuntimeError("Module '%s' not found", path);
    return mod;
}

Referenced by getConnection(), getRequiredModule(), processConnectCommand(), processModuleSpecificCommand(), and processSetParamCommand().

getRequiredModule() [2/2]

cModule * inet::ScenarioManager::getRequiredModule ( const cXMLElement *  node, const char *  attr  )

protected

{
    return getRequiredModule(xmlutils::getMandatoryFilledAttribute(*node, attr));
}

handleMessage()

void inet::ScenarioManager::handleMessage ( cMessage *  msg )

overrideprotectedvirtual

{
    auto node = check_and_cast<ScenarioTimer *>(msg)->getXmlNode();
    delete msg;
 
    processCommand(node);
 
    numDone++;
}

initialize()

void inet::ScenarioManager::initialize ( )

overrideprotectedvirtual

{
    cXMLElement *script = par("script");
 
    numChanges = numDone = 0;
    WATCH(numChanges);
    WATCH(numDone);
 
    for (cXMLElement *node = script->getFirstChild(); node; node = node->getNextSibling()) {
        // check attr t is present
        const char *tAttr = node->getAttribute(ATTR_T);
        if (!tAttr)
            throw cRuntimeError("Attribute 't' missing at %s", node->getSourceLocation());
 
        // schedule self-message
        simtime_t t = SimTime::parse(tAttr);
        auto msg = new ScenarioTimer("scenario-event");
        msg->setXmlNode(node);
        scheduleAt(t, msg);
 
        // count it
        numChanges++;
    }
}

processAtCommand()

void inet::ScenarioManager::processAtCommand ( const cXMLElement *  node )

protectedvirtual

{
    for (const cXMLElement *child = node->getFirstChild(); child; child = child->getNextSibling())
        processCommand(child);
}

Referenced by processCommand().

processCommand()

void inet::ScenarioManager::processCommand ( const cXMLElement *  node )

protectedvirtual

{
    try {
        std::string tag = node->getTagName();
        EV << "processing <" << tag << "> command...\n";
 
        if (tag == CMD_AT)
            processAtCommand(node);
        else if (tag == CMD_SET_PARAM)
            processSetParamCommand(node);
        else if (tag == CMD_SET_CHANNEL_PARAM)
            processSetChannelParamCommand(node);
        else if (tag == CMD_CREATE_MODULE)
            processCreateModuleCommand(node);
        else if (tag == CMD_DELETE_MODULE)
            processDeleteModuleCommand(node);
        else if (tag == CMD_CONNECT)
            processConnectCommand(node);
        else if (tag == CMD_DISCONNECT)
            processDisconnectCommand(node);
        else if (tag == CMD_INITIATE || tag == OP_START || tag == OP_STARTUP || tag == OP_STOP
                 || tag == OP_SHUTDOWN || tag == OP_CRASH || tag == OP_SUSPEND || tag == OP_RESUME)
            processLifecycleCommand(node);
        else
            processModuleSpecificCommand(node);
    }
    catch (std::exception& e) {
        throw cRuntimeError("%s, in command <%s> at %s", e.what(), node->getTagName(), node->getSourceLocation());
    }
}

Referenced by handleMessage(), and processAtCommand().

processConnectCommand()

void inet::ScenarioManager::processConnectCommand ( const cXMLElement *  node )

protectedvirtual

{
    cGate *srcGate;
    cModule *srcMod = getRequiredModule(node, ATTR_SRC_MODULE);
    const char *srcGateStr = xmlutils::getMandatoryFilledAttribute(*node, ATTR_SRC_GATE);
    std::string srcGateName;
    int srcGateIndex;
    parseIndexedName(srcGateStr, srcGateName, srcGateIndex);
    bool isSrcGateInOut = (srcMod->gateType(srcGateName.c_str()) == cGate::INOUT);
 
    cGate *destGate;
    cModule *destMod = getRequiredModule(node, ATTR_DEST_MODULE);
    const char *destGateStr = xmlutils::getMandatoryFilledAttribute(*node, ATTR_DEST_GATE);
    std::string destGateName;
    int destGateIndex;
    parseIndexedName(destGateStr, destGateName, destGateIndex);
    bool isDestGateInOut = (destMod->gateType(destGateName.c_str()) == cGate::INOUT);
 
    if (srcMod->getParentModule() != destMod->getParentModule())
        throw cRuntimeError("'src-module' and 'dest-module' must have the same parent module");
 
    // process <connect-channel> command
    const char *channelTypeName = node->getAttribute(ATTR_CHANNEL_TYPE);
    cChannelType *channelType = channelTypeName ? cChannelType::get(channelTypeName) : nullptr;
    cXMLElementList paramList;
 
    if (channelTypeName)
        paramList = node->getChildrenByTagName(TAG_PARAM);
 
    srcGate = isSrcGateInOut ?
        srcMod->gateHalf(srcGateName.c_str(), cGate::OUTPUT, srcGateIndex) :
        srcMod->gate(srcGateName.c_str(), srcGateIndex);
    destGate = isDestGateInOut ?
        destMod->gateHalf(destGateName.c_str(), cGate::INPUT, destGateIndex) :
        destMod->gate(destGateName.c_str(), destGateIndex);
 
    createConnection(paramList, channelType, srcGate, destGate);
 
    if (isSrcGateInOut && isDestGateInOut) {
        destGate = srcMod->gateHalf(srcGateName.c_str(), cGate::INPUT, srcGateIndex);
        srcGate = destMod->gateHalf(destGateName.c_str(), cGate::OUTPUT, destGateIndex);
 
        createConnection(paramList, channelType, srcGate, destGate);
    }
}

Referenced by processCommand().

processCreateModuleCommand()

void inet::ScenarioManager::processCreateModuleCommand ( const cXMLElement *  node )

protectedvirtual

{
    const char *moduleTypeName = xmlutils::getMandatoryFilledAttribute(*node, ATTR_TYPE);
    const char *submoduleName = xmlutils::getMandatoryFilledAttribute(*node, ATTR_SUBMODULE);
    const char *parentModulePath = xmlutils::getMandatoryFilledAttribute(*node, ATTR_PARENT);
    cModuleType *moduleType = cModuleType::get(moduleTypeName);
    cModule *parentModule = getSimulation()->getSystemModule()->getModuleByPath(parentModulePath);
    if (parentModule == nullptr)
        throw cRuntimeError("Parent module '%s' is not found", parentModulePath);
 
    // TODO solution for inconsistent out-of-date vectorSize values in OMNeT++
    int submoduleVectorSize = 0;
    for (SubmoduleIterator it(parentModule); !it.end(); ++it) {
        cModule *submodule = *it;
        if (submodule->isVector() && submodule->isName(submoduleName)) {
            if (submoduleVectorSize < submodule->getVectorSize())
                submoduleVectorSize = submodule->getVectorSize();
        }
    }
 
    bool vector = xmlutils::getAttributeBoolValue(node, ATTR_VECTOR, submoduleVectorSize > 0);
    cModule *module = nullptr;
    if (vector) {
        if (!parentModule->hasSubmoduleVector(submoduleName)) {
            parentModule->addSubmoduleVector(submoduleName, submoduleVectorSize + 1);
        }
        else
            parentModule->setSubmoduleVectorSize(submoduleName, submoduleVectorSize + 1);
        module = moduleType->create(submoduleName, parentModule, submoduleVectorSize);
    }
    else {
        module = moduleType->create(submoduleName, parentModule);
    }
    module->finalizeParameters();
    module->buildInside();
    cPreModuleInitNotification pre;
    pre.module = module;
    emit(POST_MODEL_CHANGE, &pre);
    module->callInitialize();
    cPostModuleInitNotification post;
    post.module = module;
    emit(POST_MODEL_CHANGE, &post);
}

Referenced by processCommand().

processDeleteModuleCommand()

void inet::ScenarioManager::processDeleteModuleCommand ( const cXMLElement *  node )

protectedvirtual

{
    const char *modulePath = xmlutils::getMandatoryFilledAttribute(*node, ATTR_MODULE);
    cModule *module = getSimulation()->getSystemModule()->getModuleByPath(modulePath);
    if (module == nullptr)
        throw cRuntimeError("Module '%s' not found", modulePath);
    module->callFinish();
    module->deleteModule();
}

Referenced by processCommand().

processDisconnectCommand()

void inet::ScenarioManager::processDisconnectCommand ( const cXMLElement *  node )

protectedvirtual

{
    // process <disconnect> command
    GatePair pair = getConnection(node);
 
    EV << "Disconnecting " << pair.first->getFullPath() << " --> " << pair.first->getNextGate()->getFullPath()
       << (pair.second ? " and its reverse connection" : "") << "\n";
 
    disconnect(pair.first);
    if (pair.second)
        disconnect(pair.second);
}

Referenced by processCommand().

processLifecycleCommand()

void inet::ScenarioManager::processLifecycleCommand ( const cXMLElement *  node )

protectedvirtual

{
    // resolve target module
    const char *target = node->getAttribute(ATTR_MODULE);
    cModule *module = getModuleByPath(target);
    if (!module)
        throw cRuntimeError("Module '%s' not found", target);
 
    // resolve operation
    std::string tag = node->getTagName();
    std::string operationName = (tag == CMD_INITIATE) ? node->getAttribute(ATTR_OPERATION) : tag;
    LifecycleOperation *operation;
    if (operationName == OP_START || operationName == OP_STARTUP)
        operation = new ModuleStartOperation;
    else if (operationName == OP_STOP || operationName == OP_SHUTDOWN)
        operation = new ModuleStopOperation;
    else if (operationName == OP_CRASH)
        operation = new ModuleCrashOperation;
    else
        operation = check_and_cast<LifecycleOperation *>(inet::utils::createOne(operationName.c_str()));
 
    auto paramsCopy = node->getAttributes();
    paramsCopy.erase(ATTR_MODULE);
    paramsCopy.erase(ATTR_T);
    paramsCopy.erase(ATTR_OPERATION);
    operation->initialize(module, paramsCopy);
    if (!paramsCopy.empty())
        throw cRuntimeError("Unknown parameter '%s' for operation %s", paramsCopy.begin()->first.c_str(), operationName.c_str());
 
    // do the operation
    initiateOperation(operation);
}

Referenced by processCommand().

processModuleSpecificCommand()

void inet::ScenarioManager::processModuleSpecificCommand ( const cXMLElement *  node )

protectedvirtual

{
    // find which module we'll need to invoke
    cModule *mod = getRequiredModule(node, ATTR_MODULE);
 
    // see if it supports the IScriptable interface
    IScriptable *scriptable = dynamic_cast<IScriptable *>(mod);
    if (!scriptable)
        throw cRuntimeError("<%s> not understood: it is not a built-in command of %s, and module class %s "
                            "is not scriptable (does not subclass from IScriptable)",
                node->getTagName(), getClassName(), mod->getClassName());
 
    // ok, trust it to process this command
    scriptable->processCommand(*node);
}

Referenced by processCommand().

processSetChannelParamCommand()

void inet::ScenarioManager::processSetChannelParamCommand ( const cXMLElement *  node )

protectedvirtual

{
    // process <set-channel-param> command
    GatePair pair = getConnection(node);
    const char *parAttr = xmlutils::getMandatoryFilledAttribute(*node, ATTR_PAR);
    const char *valueAttr = xmlutils::getMandatoryAttribute(*node, ATTR_VALUE);
 
    EV << "Setting channel parameter: " << parAttr << " = " << valueAttr
       << " on connection " << pair.first->getFullPath() << " --> " << pair.first->getNextGate()->getFullPath()
       << (pair.second ? " and its reverse connection" : "") << "\n";
    bubble((std::string("setting channel parameter: ") + parAttr + " = " + valueAttr).c_str());
 
    setChannelParam(pair.first, parAttr, valueAttr);
    if (pair.second)
        setChannelParam(pair.second, parAttr, valueAttr);
}

Referenced by processCommand().

processSetParamCommand()

void inet::ScenarioManager::processSetParamCommand ( const cXMLElement *  node )

protectedvirtual

{
    // process <set-param> command
    cModule *mod = getRequiredModule(node, ATTR_MODULE);
    const char *parAttr = xmlutils::getMandatoryFilledAttribute(*node, ATTR_PAR);
    const char *valueAttr = xmlutils::getMandatoryAttribute(*node, ATTR_VALUE);
 
    EV << "Setting " << mod->getFullPath() << "." << parAttr << " = " << valueAttr << "\n";
    bubble((std::string("setting: ") + mod->getFullPath() + "." + parAttr + " = " + valueAttr).c_str());
 
    // set the parameter to the given value
    cPar& param = mod->par(parAttr);
    param.parse(valueAttr);
}

Referenced by processCommand().

refreshDisplay()

void inet::ScenarioManager::refreshDisplay ( ) const

overrideprotectedvirtual

{
    char buf[80];
    sprintf(buf, "total %d changes, %d left", numChanges, numChanges - numDone);
    getDisplayString().setTagArg(ATTR_T, 0, buf);
}

setChannelParam()

void inet::ScenarioManager::setChannelParam ( cGate *  srcGate, const char *  name, const char *  value  )

protected

{
    // make sure gate is connected at all
    if (!srcGate->getNextGate())
        throw cRuntimeError("Gate '%s' is not connected", srcGate->getFullPath().c_str());
 
    // get channel object
    cChannel *chan = srcGate->getChannel();
    if (!chan)
        throw cRuntimeError("Connection starting at gate '%s' has no channel object", srcGate->getFullPath().c_str());
 
    // set the parameter to the given value
    cPar& param = chan->par(name);
    param.parse(value);
}

Referenced by processSetChannelParamCommand().

Member Data Documentation

numChanges

int inet::ScenarioManager::numChanges = 0

protected

Referenced by initialize(), and refreshDisplay().

numDone

int inet::ScenarioManager::numDone = 0

protected

Referenced by handleMessage(), initialize(), and refreshDisplay().

---

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

• ScenarioManager.h
• ScenarioManager.cc