gymwipe.networking.construction module

The construction module provides classes for building network stack representations. The concept of modules, compound modules, and gates is borrowed from the OMNeT++ model structure, which is described in [VH08].

class Gate(name, owner=None)

Bases: object

Gates provide features for the transfer of arbitrary objects. They can be connected to each other and offer a send() method that passes an object to all connected gates, as shown in the figure below, where connections are depicted as arrows.

Gates emulate the transmission of objects via connections by calling send() on their connected gates as illustrated below.

name

The Gate’s name

Type:str

nReceives

A notifier that is triggered when send() is called, providing the value passed to send()

Type:gymwipe.simtools.Notifier

nConnectsTo

A notifier that is triggered when connectTo() is called, providing the gate passed to connectTo()

Type:Notifier

connectTo(gate)

Connects this Gate to the provided Gate. Thus, if send() is called on this Gate, it will also be called on the provided Gate.

Parameters:gate (Gate) – The Gate for the connection to be established to

send(object)

Triggers nReceives with the provided object and sends it to all connected gates.

class Port(name, owner=None)

Bases: object

A Port simplifies the setup of bidirectional connections by wrapping an input and an output Gate and offering two connection methods: biConnectWith() and biConnectProxy().

Parameters:

• name (str) – The Port’s name
• owner (Any) – The object that the Port belongs to (e.g. a Module)

name

The port’s name, as provided to the constructor

Type:str

input

The port’s input Gate

output

The port’s output Gate

biConnectWith(port)

Shorthand for

self.output.connectTo(port.input)
port.output.connectTo(self.input)

Creates a bidirectional connection between this port an the passed port. If indicates input gates and indicates output gates, the resulting connection between two ports can be visualized like this:

Parameters:port (Port) – The Port to establish the bidirectional connection to

biConnectProxy(port)

Shorthand for

self.output.connectTo(port.output)
port.input.connectTo(self.input)

If indicates input gates and indicates output gates, the resulting connection between two ports can be visualized like this:

Parameters:port (Port) – The Port to establish the bidirectional proxy connection to

nReceives

The input Gate’s nReceives Notifier, which is triggered when an object is received by the input Gate.

Type:Notifier

class GateListener(gateName, validTypes=None, blocking=True, queued=False)

Bases: object

A factory for decorators that allow to call a module’s method (or process a SimPy generator method) whenever a specified gate of a Module receives an object. The received object is provided to the decorated method as a parameter.

Note

In order to make this work for a class’ methods, you have to decorate that class’ constructor with @PortListener.setup.

Examples

A Module’s method using this decorator could look like this:

@GateListener("myPortIn")
def myPortInListener(self, obj):
    # This  method is processed whenever self.gates["myPortIn"]
    # receives an object and all previously created instances
    # have been processed.
    yield SimMan.timeout(1)

Parameters:

• gateName (str) – The index of the module’s Gate to listen on
• validTypes (Union[type, Tuple[type], None]) – If this argument is provided, a TypeError will be raised when an object received via the specified Gate is not of the type / one of the types specified.
• blocking (bool) – Set this to False if you decorate a SimPy generator method and want it to be processed for each received object, regardless of whether an instance of the generator is still being processed or not. By default, only one instance of the decorated generator method is run at a time (blocking is True).
• queued (bool) – If you decorate a SimPy generator method, blocking is True, and you set queued to True, an object received while an instance of the generator is being processed will be queued. Sequentially, a new generator instance will then be processed for every queued object as soon as a previous generator instance has been processed. Using queued, you can, for example, react to multiple objects that are received at the same simulated time, while only having one instance of a subscribed generator method processed at a time. Queued defaults to False.

static setup(function)

A decorator to be used for the constructors of Module subclasses that apply the GateListener decorator.

class Module(name, owner=None)

Bases: object

Modules are used to model components that interact with each other, as for example network stack layers. A module has a number of ports and gates that can be used to exchange data with it and connect it to other modules. Modules provide the methods _addPort() and _addGate() that allow to add ports and gates, which can be accessed via the ports and the gates dictionaries.

Note

Modules may have both ports (for bidirectional connections) and individual gates (for unidirectional connections). When a port is added by _addPort(), its two gates are also added to the gates dictionary.

name

The Module’s name

Type:str

ports

The Module’s outer Ports

Type:Dict[str, Port]

gates

The Module’s outer Gates

Type:Dict[str, Gate]

_addPort(name)

Adds a new Port to the ports dictionary, indexed by the name passed. Since a Port holds two Gate objects, a call of this method also adds two entries to the gates dictionary, namely “<name>In” and “<name>Out”.

Parameters:name (str) – The name for the Port to be indexed with

_addGate(name)

Adds a new Gate to the gates dictionary, indexed by the name passed.

Note

Plain Gate objects are only needed for unidirectional connections. Bidirectional connections can profit from Port objects.

Parameters:name (str) – The name for the Gate to be indexed with

class CompoundModule(name, owner=None)

Bases: gymwipe.networking.construction.Module

A CompoundModule is a Module that contains an arbitrary number of submodules (Module objects) which can be connected with each other and their parent module’s gates and ports. Submodules are added using _addSubmodule() and can be accessed via the submodules dictionary.

Note

When subclassing CompoundModule, do not directly implement functionalities in your subclass, but wrap them in submodules to ensure modularity. Also, do not connect a CompoundModule’s submodules to anything else than other submodules or the CompoundModule itself for the same reason.

submodules

The CompoundModule’s nested Module objects

Type:Dict[str, Module]

_addSubmodule(name, module)

Adds a new Module to the submodules dictionary, indexed by the name passed.

Parameters:

• name (str) – The name for the submodule to be indexed with
• module (Module) – The Module object to be added as a submodule