Developers documentation

MAD Engine

class engine.Mad(ass)

This class is the engine of the Madeus model. When running it first check if the assembly has warnings, then it calls the mad_engine method to run the semantics on the assembly.

check_warnings()

This method is called before runing an assembly. It checks components and their connections. The default behavior is to block the run if some warnings are detected.

Returns:True if no WARNINGS, False otherwise

mad_engine(dryrun, printing)

This is the main function to run the operational semantics of the Madeus formal model. This is the heart of the coordination engine.

run(force=False, dryrun=False, printing=True)

This method run the assembly after checking its validity

Assembly

class assembly.Assembly

This Assembly class is used to create a assembly.

An assembly is a set of component instances and the connection of their dependencies.

addComponent(name, comp)

This method adds a component instance to the assembly

Parameters:comp – the component instance to add

addConnection(comp1, name1, comp2, name2)

This method adds a connection between two components dependencies.

Parameters:

• comp1 – The first component to connect
• name1 – The dependency name of the first component to connect
• comp2 – The second component to connect
• name2 – The dependency name of the second component to connect

check_warnings()

This method check WARNINGS in the structure of an assembly.

Returns:false if some WARNINGS have been detected, true otherwise

component_connections = {}

BUILD ASSEMBLY

disable_enable_connections(printing)

This method build the new list of enabled connections according to the current states of “activated” places (ie the ones getting a token).

Parameters:configuration – the current configuration of the deployment Returns:the new list of activated connections

init_semantics()

This method activate the initial places of each component and builds the global self.act_places

is_finish()

This method checks if the deployment is finished

Parameters:configuration – the current configuration of the deployment Returns:True if the deployment is finished, False otherwise

semantics(dryrun, printing)

This method runs one semantics iteration by first updating the list of enbled connections and then by running semantics of each component of the assembly. :param dryrun: boolean representing if the semantics is run in dryrun mode :param printing: boolean representing if the semantics must print output

class assembly.Connection(comp1, dep1, comp2, dep2)

This class is used by the assembly to store connections between components

Configuration

class configuration.Configuration(pla, conn)

This class represents a configuration of the Madeus formal model. However, unlike the formal model and for performance reasons, the global configuration only stores active places and connections. Actually, each component stores its local set of actives places, transitions, input docks and output docks. A configuration is used by the engine to know the state of a deployment.

get_connections()

This method returns the list of active connections of the configuration

Returns:self.connections

get_places()

This method returns the list of active places of the configuration

Returns:self.places

update_connections(conn)

This method updates the connections of the configuration

Parameters:conn – new list of active connections

update_places(pla)

This method updates the places of the configuration

Parameters:pla – new list of active places

Component

class component.Component

This Component class is used to create a component.

A component is a software module to deploy. It is composed of places, transitions between places, dependencies and bindings between dependencies and Places/transitions.

This is an abstract class that need to be override.

add_dependencies(dep)

This method add all dependencies declared in the user component class as a dictionary associating the name of a dependency to both a type and the name of the transition or the place to which it is bound.

• a ‘use’ or ‘data-use’ dependency can be bound to a transition
• a ‘provide’ or ‘data-provide’ dependency can be bound to a place

Parameters:dep – dictionary of dependencies

add_dependency(name, type, bindings)

This method offers the possibility to add a single dependency to an already existing dictionary of dependencies.

Parameters:

• name – the name of the dependency to add
• type – the type DepType of the dependency
• binding – the name of the binding of the dependency (place or transition)

add_place(name)

This method offers the possibility to add a single place to an already existing dictionary of places.

Parameters:name – the name of the place to add

add_places(places)

This method add all places declared in the user component class as a dictionary associating the name of a place to its number of input and output docks.

Parameters:places – dictionary of places

add_transition(name, src, dst, func, args=())

This method offers the possibility to add a single transition to an already existing dictionary of transitions.

Parameters:

• name – the name of the transition to add
• src – the name of the source place of the transition
• dst – the name of the destination place of the transition
• func – a functor created by the user
• args – optional tuple of arguments to give to the functor

add_transitions(transitions)

This method add all transitions declared in the user component class as a dictionary associating the name of a transition to a transition object created by the user too.

Parameters:transitions – dictionary of transitions

check_connections()

This method check connections once the component has been instanciated and connected in an assembly. This method is called by the engine -> assembly

Returns:True if all dependencies of a component are connected, False otherwise

check_warnings()

This method check WARNINGS in the structure of the component.

Returns:False if some WARNINGS have been detected, True otherwise.

end_transition(dryrun)

This method try to join threads from currently running transitions. For joined transitions, the dst_docks (ie input docks of the assembly) are stored for the new configuration. Un-joined transitions are stored for the new configuration.

Parameters:dryrun – to indicate if the assembly is executed in dryrun mode. Returns:return (still_running, new_idocks)

Elements of the returned tuple are the list of transitions still running and the list of new input docks resulting from finished transitions in a pair.

get_dependency(name)

This method returns the dependencies object associated to a given name

Parameters:name – the name (string) of the dependency to get Returns:the dependency object associated to the name

get_places()

This method returns the dictionary of places of the component

Returns:self.st_places the dictionary of places

getcolor()

This method returns the color associated to the current component

Returns:the printing color of the component

getname()

This method returns the name of the component

Returns:the name (string) of the component

idocks_in_place()

This method returns the list of new places enabled. These places come from their set of input docks, all ready.

Returns:(new_place, still_idocks)

Elements of the returned tuple are the new list of new enabled places, and the list of input docks without modification

init_places()

This method initializes the initial activated places of the component in its local configuration self.act_places

init_trans_connections(comp_connections)

This method initializes the dictionary associating one transition to a set of connections. This dictionary is used to start a transition. :param comp_connections: the list of all connections associated to the current component.

isconnected(name)

This method is used to know if a given dependency is connected or not :param name: name of the dependency :return: True if connected, False otherwise

place_in_odocks(my_connections)

This method represents the one moving the token of a place to its output docks.

Parameters:my_connections – the list of enabled connections of the current

component. :return: (new_odocks, still_place)

Elements of the returned tuple are the new list of output docks and the list of places that cannot move to output docks (possible because of groups and dependencies on services).

semantics(my_connections, dryrun, printing)

This method apply the operational semantics at the component level. It takes as input the current configuration of the deployment which represents runtime information.

Parameters:configuration – The current configuration of the deployment Returns:a tuple (new_transitions, new_places, new_idocks, new_odocks)

Elements of the returned tuple are respectively the list of components, transitions, places, input docks and output docks in the new configuration of the current component.

setcolor(c)

This method set a printing color to the current component

Parameters:c – the color to set

setname(name)

This method sets the name of the current component

Parameters:name – the name (string) of the component

start_transition(my_connections, dryrun)

This method start the transitions ready to run:

• source dock of the transition in the list of activated output docks
• all dependencies required by the transition in an activated connection

Parameters:

• my_connections – list of connections associated to the current component
• dryrun – to indicate if the assembly is executed in dryrun mode.

Returns:

(new_transitions, still_odocks)

Elements of the returned tuple are the list of new transitions started by the method and the list of output docks still waiting for connections.

class component.Group

This class is used to create a group object within a Component. A group is a set of places and transitions to which a service provide dependency is bound. This object facilitate the semantics and its efficiency.

Place

class place.Dock(place, type, transition)

This Dock class is used to create a dock.

A dock is an input or an output of a place.

getplace()

This method returns the Place object associated to the dock

Returns:a Place object

gettype()

This method returns the type of dock

Returns:self.DOCK_TYPE

class place.Place(name)

This Place class is used to create a place of a component.

A place represents an evolution state in the deployment of a component.

add_provide(dep)

This method is used to add a provide dependency bound to the current place

Parameters:dep – the provide dependency to add

create_input_dock(transition)

This method creates an additional input dock to the current place. This method is called by Transition. An input dock of a place corresponds to a destination dock of a transition.

Parameters:transition – the transition to which the dock will be associated Returns:the new input dock

create_output_dock(transition)

This method creates an additional output dock to the current place. This method is called by Transition. An output dock of a place corresponds to a source dock of a transition.

Parameters:transition – the transition to which the dock will be associated Returns:the new output dock

get_inputdocks()

This method returns the list of input docks of the place

Returns:self.input_docks

get_outputdocks()

This method returns the list of output docks of the place

Returns:self.output_docks

get_provides()

This method returns the list of provide dependencies bound to the current place

Returns:self.provides

getname()

This method returns the name of the place

Returns:name

Transition

class transition.Transition(name, src, dst, func, args, places)

This Transition class is used to create a transition.

A transition is an action, represented by the ‘run’ function. This action is performed between a source and destination dock, each of which is attached to a place.

This is an abstract class that need to be override. In particular, the method ‘run’ must be override

bind_docks(places)

This method is called from the Component class to create docks into places associated to the transition. Once created these docks are bound to the transition.

Parameters:places – the dictionary of all places declared for the component

get_dst_dock()

This method returns the destination dock of the transition

Returns:the destination dock self.dst_dock

get_src_dock()

This method returns the source dock of the transition

Returns:the source dock self.src_dock

getname()

This method returns the name of the transition

Returns:name (string)

join_thread(dryrun)

This method tries to join self.thread. The default behavior has no timeout.

Returns:True if the tread has been joined, False othwise

setname(name)

This method set the name of the transition

Parameters:name – tha name (string) to set

start_thread(dryrun)

This method creates the thread of the transition

Returns:the Thread of the transition

Dependency

class dependency.DepMandatory

This class is not instanciated and is an Enumeration. It is used to know if a dependency is mandatory or optional.

class dependency.DepType

This class is not instanciated. It handles the types of dependencies.

class dependency.Dependency(name, type, bindings)

This class represents a dependency.

connect()

This method set self.free to False to indicate that the dependency has been connected in the assembly. Note that a dependency can be connected more than once, however this method is used to throw a warning when dependencies are not connected.

Returns:self.free

connectwb(wb)

This method set self.free to False to indicate that the dependency has been connected in the assembly. Note that a dependency can be connected more than once, however this method is used to throw a warning when dependencies are not connected.

Returns:self.free

getbindings()

This method returns the place or the transition to which the dependency is bound. If the dependency is of type DepType.USE or DepType.DATA_USE it is bound to a transition, otherwise it is bound to a place.

Returns:the transition or the place self.binding

getname()

This method returns the name of the dependency

Returns:name

gettype()

This method returns the type of the dependency DepType

Returns:type

isfree()

This method indicates if the dependency is free or not, ie if it is already connected to another dependency within the assembly

Returns:True if not connected, False if free

Utility

class utility.Messages

This class is not instanciated. It is used for valid, warning, and fail color-printed messages.