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 ()
virtual	~LifecycleController ()
virtual bool	initiateOperation (LifecycleOperation *operation, IDoneCallback *completionCallback=nullptr)
	Initiate an operation. More...

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

Protected Attributes
Callback *	spareCallback = nullptr

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

LifecycleController()

inet::LifecycleController::LifecycleController ( )

inline

: spareCallback(nullptr) {}

~LifecycleController()

virtual inet::LifecycleController::~LifecycleController ( )

inlinevirtual

{ delete spareCallback; }

Member Function Documentation

doOneStage()

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

protectedvirtual

{
    ILifecycle *subject = dynamic_cast<ILifecycle *>(submodule);
    if (subject) {
        Callback *callback = spareCallback ? spareCallback : new Callback();
        bool done = subject->handleOperationStage(operation, 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);
    }
}

Referenced by resumeOperation().

initiateOperation()

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.

{
    ASSERT(getSimulation()->getContextModule() == check_and_cast<cComponent *>(this));
    operation->currentStage = 0;
    operation->operationCompletionCallback = completionCallback;
    operation->insideInitiateOperation = true;
    return resumeOperation(operation);
}

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

moduleOperationStageCompleted()

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

protectedvirtual

{
    omnetpp::cMethodCallContextSwitcher __ctx(check_and_cast<cComponent *>(this)); __ctx.methodCall(__FUNCTION__);
#ifdef INET_WITH_SELFDOC
    __Enter_Method_SelfDoc(__FUNCTION__);
#endif
 
    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);
    }
}

resumeOperation()

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

protectedvirtual

{
    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
}

Referenced by initiateOperation(), and moduleOperationStageCompleted().

Member Data Documentation

spareCallback

Callback* inet::LifecycleController::spareCallback = nullptr

protected

Referenced by doOneStage().

---

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

• LifecycleController.h
• LifecycleController.cc