inet::LifecycleController Class Reference

Manages operations like shutdown/restart, suspend/resume, crash/recover and similar operations for nodes (routers, hosts, etc), interfaces, and protocols. More...

#include <LifecycleController.h>

Inheritance diagram for inet::LifecycleController:

Classes
class	Callback

Public Member Functions
	LifecycleController ()
	~LifecycleController ()
virtual void	initialize () override
virtual void	handleMessage (cMessage *msg) override
virtual void	processCommand (const cXMLElement &node) override
	Called by ScenarioManager whenever a script command needs to be carried out by the module. More...
virtual bool	initiateOperation (LifecycleOperation *operation, IDoneCallback *completionCallback=nullptr)
	Initiate an operation. More...
Public Member Functions inherited from inet::IScriptable
virtual	~IScriptable ()

Protected Member Functions
virtual bool	resumeOperation (LifecycleOperation *operation)
virtual void	doOneStage (LifecycleOperation *operation, cModule *submodule)
virtual void	moduleOperationStageCompleted (Callback *callback)

Protected Attributes
Callback *	spareCallback

Detailed Description

Manages operations like shutdown/restart, suspend/resume, crash/recover and similar operations for nodes (routers, hosts, etc), interfaces, and protocols.

Overview and usage are described in the NED file, you are advised to read that first. The rest of this documentation concentrates on the C++ API.

Operations are represented by C++ class derived from LifecycleOperation. Simple modules that wish to participate in an operation need to implement the ILifecycle interface (C++ class).

An operation is initiated by calling the initiateStateChange(cModule *module, LifecycleOperation *operation) method of this class. (This is often done from a ScenarioManager script). This method applies the operation to the given module (usually a host, router or network interface compound module).

Operations may have multiple stages (think multi-stage initialization), where each stage may take nonzero simulation time. The number of stages are defined by the operation (its getNumStages() method). Within a stage, the submodule tree is traversed, and initiateStateChange() is invoked on each module that implements ILifecycle.

Operations may take nonzero simulation time. A module that needs nonzero simulation time to complete a stage (e.g. it wants to close TCP connections or model finite shutdown/reboot time) can signal that in the return value of initiateStateChange(). When it is done, it can signal that to LifecycleController by invoking the callback passed to it in initiateStateChange(). LifecycleController only regards the stage as completed (and goes on to the next stage) when all participating modules have indicated that they are done.

Operations can be nested, that is, it's possible to initiate another operation while one is underway.

See also

ILifecycle, LifecycleOperation

Constructor & Destructor Documentation

inet::LifecycleController::LifecycleController ( )

inline

: spareCallback(nullptr) {}

inet::LifecycleController::~LifecycleController ( )

inline

{ delete spareCallback; }

Member Function Documentation

void inet::LifecycleController::doOneStage ( LifecycleOperation *  operation, cModule *  submodule  )

protectedvirtual

Referenced by resumeOperation().

{
    ILifecycle *subject = dynamic_cast<ILifecycle *>(submodule);
    if (subject) {
        Callback *callback = spareCallback ? spareCallback : new Callback();
        bool done = subject->handleOperationStage(operation, operation->currentStage, callback);
        if (!done) {
            callback->init(this, operation, submodule);
            operation->pendingList.push_back(callback);
            spareCallback = nullptr;
        }
        else
            spareCallback = callback;
    }

    for (cModule::SubmoduleIterator i(submodule); !i.end(); i++) {
        cModule *child = *i;
        doOneStage(operation, child);
    }
}

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

overridevirtual

{
    throw cRuntimeError("This module does not process messages");
}

void inet::LifecycleController::initialize ( )

overridevirtual

{
}

bool inet::LifecycleController::initiateOperation ( LifecycleOperation *  operation, IDoneCallback *  completionCallback = nullptr  )

virtual

Initiate an operation.

See the class documentation and ILifecycle for details. The target module will be taken from the operation object.

The return value indicates whether the operation has been completed inside the call (true), or is pending because it will take several events and likely nonzero simulation time to complete (false). In the latter case, and if you provided a completionCallback as parameter, you will be notified via the callback when the operation completes.

Referenced by inet::power::SimpleEpEnergyManagement::executeNodeOperation(), inet::power::SimpleCcBattery::executeNodeOperation(), inet::power::SimpleEpEnergyStorage::executeNodeOperation(), and processCommand().

{
    Enter_Method_Silent();
    operation->currentStage = 0;
    operation->operationCompletionCallback = completionCallback;
    operation->insideInitiateOperation = true;
    return resumeOperation(operation);
}

void inet::LifecycleController::moduleOperationStageCompleted ( Callback *  callback )

protectedvirtual

Referenced by inet::LifecycleController::Callback::invoke().

{
    Enter_Method_Silent();

    LifecycleOperation *operation = callback->operation;
    std::string moduleFullPath = callback->module->getFullPath();
    vector_delete_element(operation->pendingList, (IDoneCallback *)callback);

    EV << "Module " << moduleFullPath << " completed stage "
       << operation->currentStage << " of operation " << operation->getClassName() << ", "
       << operation->pendingList.size() << " more module(s) pending"
       << (operation->pendingList.empty() ? ", stage completed" : "") << endl;

    if (operation->pendingList.empty()) {
        operation->currentStage++;
        operation->insideInitiateOperation = false;
        resumeOperation(operation);
    }
}

void inet::LifecycleController::processCommand ( const cXMLElement &  node )

overridevirtual

Called by ScenarioManager whenever a script command needs to be carried out by the module.

The command is represented by the XML element or element tree. The command name can be obtained as:

const char *command = node->getTagName()

Parameters are XML attributes, e.g. a "neighbour" parameter can be retrieved as:

const char *attr = node->getAttribute("neighbour")

More complex input can be passed in child elements.

See also

cXMLElement

Implements inet::IScriptable.

{
    // resolve target module
    const char *target = node.getAttribute("target");
    cModule *module = getModuleByPath(target);
    if (!module)
        throw cRuntimeError("Module '%s' not found", target);

    // resolve operation
    const char *operationName = node.getAttribute("operation");
    LifecycleOperation *operation = check_and_cast<LifecycleOperation *>(inet::utils::createOne(operationName));
    std::map<std::string, std::string> params = node.getAttributes();
    params.erase("module");
    params.erase("t");
    params.erase("target");
    params.erase("operation");
    operation->initialize(module, params);
    if (!params.empty())
        throw cRuntimeError("Unknown parameter '%s' for operation %s at %s", params.begin()->first.c_str(), operationName, node.getSourceLocation());

    // do the operation
    initiateOperation(operation);
}

bool inet::LifecycleController::resumeOperation ( LifecycleOperation *  operation )

protectedvirtual

Referenced by initiateOperation(), and moduleOperationStageCompleted().

{
    int numStages = operation->getNumStages();
    while (operation->currentStage < numStages) {
        EV << "Doing stage " << operation->currentStage << "/" << operation->getNumStages()
           << " of operation " << operation->getClassName() << " on " << operation->rootModule->getFullPath() << endl;
        doOneStage(operation, operation->rootModule);
        if (operation->pendingList.empty())
            operation->currentStage++;
        else
            return false; // pending
    }

    // done: invoke callback (unless we are still under initiateOperation())
    if (operation->operationCompletionCallback && !operation->insideInitiateOperation)
        operation->operationCompletionCallback->invoke();
    delete operation;
    return true;    // done
}

Member Data Documentation

Callback* inet::LifecycleController::spareCallback

protected

Referenced by doOneStage().

---

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

• LifecycleController.h
• LifecycleController.cc