Bases: object
An Attribute exposes a configuration parameter of a resource
Returns True if the Attribute has the flag ‘flag’
| Parameters: | flag (Flags) – Flag to be checked |
|---|
Attribute subclasses will override this method to add adequate validation
Returns the value of the Attribute
Bases: object
Possible states of the ExperimentController
Bases: object
An experiment, or scenario, is defined by a concrete set of resources, and the behavior, configuration and interconnection of those resources. The Experiment Description (ED) is a detailed representation of a single experiment. It contains all the necessary information to allow repeating the experiment. NEPI allows to describe experiments by registering components (resources), configuring them and interconnecting them.
A same experiment (scenario) can be executed many times, generating different results. We call an experiment execution (instance) a ‘run’.
The ExperimentController (EC), is the entity responsible of managing an experiment run. The same scenario can be recreated (and re-run) by instantiating an EC and recreating the same experiment description.
An experiment is represented as a graph of interconnected resources. A resource is a generic concept in the sense that any component taking part of an experiment, whether physical of virtual, is considered a resource. A resources could be a host, a virtual machine, an application, a simulator, a IP address.
A ResourceManager (RM), is the entity responsible for managing a single resource. ResourceManagers are specific to a resource type (i.e. An RM to control a Linux application will not be the same as the RM used to control a ns-3 simulation). To support a new type of resource, a new RM must be implemented. NEPI already provides a variety of RMs to control basic resources, and new can be extended from the existing ones.
Through the EC interface the user can create ResourceManagers (RMs), configure them and interconnect them, to describe an experiment. Describing an experiment through the EC does not run the experiment. Only when the ‘deploy()’ method is invoked on the EC, the EC will take actions to transform the ‘described’ experiment into a ‘running’ experiment.
While the experiment is running, it is possible to continue to create/configure/connect RMs, and to deploy them to involve new resources in the experiment (this is known as ‘interactive’ deployment).
An experiments in NEPI is identified by a string id, which is either given by the user, or automatically generated by NEPI. The purpose of this identifier is to separate files and results that belong to different experiment scenarios. However, since a same ‘experiment’ can be run many times, the experiment id is not enough to identify an experiment instance (run). For this reason, the ExperimentController has two identifier, the exp_id, which can be re-used in different ExperimentController, and the run_id, which is unique to one ExperimentController instance, and is automatically generated by NEPI.
Returns True if the experiment has failed and should be interrupted, False otherwise.
Deploys all ResourceManagers in the guids list.
If the argument ‘guids’ is not given, all RMs with state NEW are deployed.
param guids: List of guids of RMs to deploy type guids: list param wait_all_ready: Wait until all RMs are ready in order to start the RMs type guid: int param group: Id of deployment group in which to deploy RMs type group: int
Discovers an available resource matching the criteria defined by the RM with guid ‘guid’, and associates that resource to the RM
Not all RM types require (or are capable of) performing resource discovery. For the RM types which are not capable of doing so, invoking this method does not have any consequences.
param guid: Guid of the RM type guid: int
Enables a trace to be collected during the experiment run
| Parameters: | name (str) – Name of the trace |
|---|
Returns the guids of all ResourceManagers of type rtype
| Parameters: | rtype (string) – Resource type |
|---|---|
| Return type: | list of guids |
Returns the value of the attribute with name ‘name’ on the RM with guid ‘guid’
param guid: Guid of the RM type guid: int param name: Name of the attribute type name: str return: The value of the attribute with name ‘name’
Returns the attribute ‘name’ of the RM with guid ‘guid’
| Parameters: | |
|---|---|
| Returns: | The attribute with name ‘name’ |
| Return type: | Attribute |
Returns all the attributes of the RM with guid ‘guid’
| Parameters: | guid (int) – Guid of the RM |
|---|---|
| Returns: | List of attributes |
| Return type: | list |
Returns the value of the global attribute with name ‘name’ on the RMs of rtype ‘rtype’.
param guid: Guid of the RM type guid: int param name: Name of the attribute type name: str return: The value of the attribute with name ‘name’
Returns a registered ResourceManager by its guid
| Parameters: | guid (int) – Id of the resource |
|---|---|
| Return type: | ResourceManager |
Returns the ResourceManager objects of type rtype
| Parameters: | rtype (string) – Resource type |
|---|---|
| Return type: | list of ResourceManagers |
Returns a task by its id
| Parameters: | tid (int) – Id of the task |
|---|---|
| Return type: | Task |
Returns the list of the trace names of the RM with guid ‘guid’
| Parameters: | guid (int) – Guid of the RM |
|---|---|
| Returns: | List of trace names |
| Return type: | list |
Reports a failure in a RM to the EC for evaluation
| Parameters: | guid (int) – Resource id |
|---|
If True, persists the ExperimentController to XML format upon experiment completion
Provisions the resource associated to the RM with guid ‘guid’.
Provisioning means making a resource ‘accessible’ to the user. Not all RM types require (or are capable of) performing resource provisioning. For the RM types which are not capable of doing so, invoking this method does not have any consequences.
param guid: Guid of the RM type guid: int
Registers an action START, STOP or DEPLOY for all RM on list guids1 to occur at time ‘time’ after all elements in list guids2 have reached state ‘state’.
param guids1: List of guids of RMs subjected to action type guids1: list param action: Action to perform (either START, STOP or DEPLOY) type action: ResourceAction param guids2: List of guids of RMs to we waited for type guids2: list param state: State to wait for on RMs of list guids2 (STARTED, STOPPED, etc) type state: ResourceState param time: Time to wait after guids2 has reached status type time: string
Registers a connection between a RM with guid ‘guid1’ and another RM with guid ‘guid2’.
The order of the in which the two guids are provided is not important, since the connection relationship is symmetric.
param guid1: First guid to connect type guid1: ResourceManager param guid2: Second guid to connect type guid: ResourceManager
Registers a new ResourceManager of type ‘rtype’ in the experiment
This method will assign a new ‘guid’ for the RM, if no guid is specified.
param rtype: Type of the RM type rtype: str return: Guid of the RM rtype: int
Releases all ResourceManagers in the guids list.
If the argument ‘guids’ is not given, all RMs registered in the experiment are released.
param guids: List of RM guids type guids: list
Returns the guids of all ResourceManagers
| Returns: | Set of all RM guids |
|---|---|
| Return type: | list |
Schedules a callback to be executed at time ‘date’.
| Parameters: |
|
|---|
:return : The Id of the task :rtype: int
Modifies the value of the attribute with name ‘name’ on the RM with guid ‘guid’.
param guid: Guid of the RM type guid: int param name: Name of the attribute type name: str param value: Value of the attribute
Modifies the value of the global attribute with name ‘name’ on the RMs of with rtype ‘rtype’.
param guid: Guid of the RM type guid: int param name: Name of the attribute type name: str param value: Value of the attribute
Modifies the value of attribute with name ‘name’ on all RMs on the guids1 list when time ‘time’ has elapsed since all elements in guids2 list have reached state ‘state’.
param name: Name of attribute to set in RM type name: string param value: Value of attribute to set in RM type name: string param guids1: List of guids of RMs subjected to action type guids1: list param action: Action to register (either START or STOP) type action: ResourceAction param guids2: List of guids of RMs to we waited for type guids2: list param state: State to wait for on RMs (STARTED, STOPPED, etc) type state: ResourceState param time: Time to wait after guids2 has reached status type time: string
Starts the RM with guid ‘guid’
Starting a RM means that the resource it controls will begin taking part of the experiment.
param guid: Guid of the RM type guid: int
Returns the state of a resource
| Parameters: |
|
|---|
Stops the RM with guid ‘guid’
Stopping a RM means that the resource it controls will no longer take part of the experiment.
param guid: Guid of the RM type guid: int
Returns information on a collected trace, the trace stream or blocks (chunks) of the trace stream
param name: Name of the trace
type name: str
param attr: Can be one of: - TraceAttr.ALL (complete trace content), - TraceAttr.STREAM (block in bytes to read starting
at offset),
- TraceAttr.PATH (full path to the trace file),
- TraceAttr.SIZE (size of trace file).
type attr: str
param block: Number of bytes to retrieve from trace, when attr is TraceAttr.STREAM
type name: int
param offset: Number of ‘blocks’ to skip, when attr is TraceAttr.STREAM
type name: int
rtype: str
Returns True if the trace of name ‘name’ is enabled
| Parameters: | name (str) – Name of the trace |
|---|
Blocking method that waits until all RMs in the ‘guids’ list have reached a state >= ‘state’, or until the ‘quit’ callback yields True
param guids: List of guids type guids: list
Blocking method that waits until all RMs in the ‘guids’ list have reached a state >= READY, or until a failure in the experiment occurs (i.e. abort == True)
param guids: List of guids type guids: list
Blocking method that waits until all RMs in the ‘guids’ list have reached a state >= STOPPED (i.e. STOPPED, FAILED or RELEASED ), or until a failure in the experiment occurs (i.e. abort == True)
param guids: List of guids type guids: list
Bases: object
Possible failure states for the experiment
Bases: object
The FailureManager is responsible for handling errors and deciding whether an experiment should be aborted or not
Action that a user can order to a Resource Manager
Bases: nepi.util.logger.Logger
Base clase for all ResourceManagers.
A ResourceManger is specific to a resource type (e.g. Node, Switch, Application, etc) on a specific platform (e.g. PlanetLab, OMF, etc).
The ResourceManager instances are responsible for interacting with and controlling concrete (physical or virtual) resources in the experimental platforms.
Returns the conditions to which the RM is subjected to.
This method returns a dictionary of conditions lists indexed by a ResourceAction.
Deploy RM when all the conditions in self.conditions for action ‘READY’ are satisfied.
Performs actions that need to be taken upon associating RMs. This method should be redefined when necessary in child classes.
Performs actions that need to be taken upon disassociating RMs. This method should be redefined when necessary in child classes.
Explicitly enable trace generation
| Parameters: | name (str) – Name of the trace |
|---|
Sets the RM to state FAILED.
This method should not be overridden directly. Specific functionality should be added in the do_fail method.
Returns the value of the attribute
| Parameters: | name (str) – Name of the attribute |
|---|---|
| Return type: | str |
Returns the list of RM with the type ‘rtype’
| Parameters: | rtype (str) – Type of the RM we look for |
|---|---|
| Returns: | list of guid |
| Parameters: | name (str) – Name of the attribute |
|---|---|
| Return type: | str |
Returns the identified of the platform (i.e. testbed type) for the Resource
Returns true if the RM has an attribute with name
| Parameters: | name (string) – name of the attribute |
|---|
| Parameters: | name (str) – Name of the attribute |
|---|---|
| Return type: | str |
Returns true if the attribute has the flag ‘flag’
| Parameters: | flag (Flags) – Flag to be checked |
|---|
Returns True if the RM is instance of ‘rtype’
| Parameters: | rtype (str) – Type of the RM we look for |
|---|---|
| Returns: | True|False |
Returns the log message formatted with added information.
| Parameters: | msg (str) – text message |
|---|---|
| Return type: | str |
Registers a condition on the resource manager to allow execution of ‘action’ only after ‘time’ has elapsed from the moment all resources in ‘group’ reached state ‘state’
| Parameters: |
|
|---|
Registers a connection to the RM identified by guid
This method should not be overridden. Specific functionality should be added in the do_connect method.
| Parameters: | guid (int) – Global unique identified of the RM to connect to |
|---|
Perform actions to free resources used by the RM.
This method is responsible for releasing resources that were used during the experiment by the RM.
This method should not be overridden directly. Specific functionality should be added in the do_release method.
Set the value of the attribute
| Parameters: |
|
|---|
Set value for a global attribute
| Parameters: |
|
|---|
Set the state of the RM while keeping a trace of the time
Set value ‘value’ on attribute with name ‘name’ when ‘time’ has elapsed since all elements in ‘group’ have reached state ‘state’
| Parameters: |
|
|---|
Starts RM when all the conditions in self.conditions for action ‘START’ are satisfied.
Stops RM when all the conditions in self.conditions for action ‘STOP’ are satisfied.
Get information on collected trace
| Parameters: |
|
|---|---|
| Return type: | str |
Returns True if trace is enables
| Parameters: | name (str) – Name of the trace |
|---|
Removed conditions for a certain group of guids
| Parameters: |
|
|---|
State of a Resource Manager
Initializes template information (i.e. attributes and traces) on classes derived from the ResourceManager class.
It is used as a decorator in the class declaration as follows:
@clsinit class MyResourceManager(ResourceManager):
...
Initializes template information (i.e. attributes and traces) on classes derived from the ResourceManager class. It differs from the clsinit method in that it forces inheritance of attributes and traces from the parent class.
It is used as a decorator in the class declaration as follows:
@clsinit class MyResourceManager(ResourceManager):
...
clsinit_copy should be prefered to clsinit when creating new ResourceManager child classes.
Decorator function for instance methods that should set the RM state to FAILED when an error is raised. The methods that must be decorated are: discover, reserved, provision, deploy, start, stop.
Bases: object
The ExperimentRunner entity is responsible of re-running an experiment described by an ExperimentController multiple time
Returns True when the confidence interval of the sample mean is less than 5% of the mean value, for a 95% confidence level, assuming normal distribution of the data
Run a same experiment independently multiple times, until the evaluate_convergence_callback function returns True
| Parameters: |
|
|---|
Bases: object
Create a Heap Scheduler
Note
This class is thread safe. All calls to C Extensions are made atomic by the GIL in the CPython implementation. heapq.heappush, heapq.heappop, and list access are therefore thread-safe.