1.5. Macro connectors for encapsulating processing networks in a class¶

Classes, which encapsulate networks of objects, that are connected with the functionalities of the Connectors package, are called macros or macro classes in the scope of this package. The connectors, that are used to export connectors from the internal network as connectors of the macro, are called macro connectors. This is the API reference for the functionalities, that are related to macro connectors.

1.5.1. Decorating methods¶

The following classes can be used to decorate methods, so they become macro connectors.

class connectors.MacroOutput¶

A decorator to replace a method with a macro output connector.

Macro connectors are useful, when a processing network shall be encapsulated in a class. In such a case, macro output connectors are used to export output connectors from the internal processing network to be accessible as connectors of the encapsulating class’s instance.

The decorated method must not take any parameters and return the output connector from the internal processing network, that it exports.

The resulting connector will behave like an output connector, which is very different from the decorated method:

the connector takes no argument.
when called, the connector returns the result of the exported connector.

class connectors.MacroInput¶

A decorator to replace a method with a macro input connector.

Macro connectors are useful, when a processing network shall be encapsulated in a class. In such a case, macro input connectors are used to export input connectors from the internal processing network to be accessible as connectors of the encapsulating class’s instance.

The decorated method must not take any parameters and yield all input connectors from the internal processing network, that it exports. Exporting multiple connectors through the same macro connector is possible and useful, when all of these connectors shall always receive the same input value.

The resulting connector will behave like an input connector, which is very different from the decorated method:

the connector’s arguments are passed to all the exported input connectors, when it is called.
when called, the connector returns the instance to which it belongs, so that changing a parameter and retrieving a result in one line is possible
when a behavior (e.g. laziness) of the connector is changed, the change is passed on to all the exported connectors.

1.5.2. Configuring macro connectors¶

Instances of the following classes replace the decorated methods, so they are enhanced with the functionality of a macro connector.

class connectors.connectors.MacroOutputConnector(instance, method)¶

A Connector-class that exports an output connector from an internal processing network to the API of the class, that encapsulates the network.

Parameters:	instance – the instance in which the method is replaced by this connector method – the unbound method, that is replaced by this connector

connect(connector)¶

Connects the exported output connector to the given input.

Parameters:	connector – the input connector to which the exported connector shall be connected
Returns:	the instance of which this connector has replaced a method

disconnect(connector)¶

Disconnects the exported output connector from the given input.

Parameters:	connector – the input connector from which the exported connector shall be disconnected
Returns:	the instance of which this connector has replaced a method

set_caching(caching)¶

Specifies, if the result value of this output connector shall be cached. If caching is enabled and the result value is retrieved (e.g. through a connection or by calling the connector), the cached value is returned and the replaced getter method is not called unless the result value has to be re-computed, because an observed setter method has changed a parameter for the computation. In this case, the getter method is only called once, independent of the number of connections through which the result value has to be passed.

Parameters:	caching – True, if caching shall be enabled, False otherwise

set_executor(executor)¶

Sets the executor, which handles the computations, when the data is retrieved through this connector. An executor can be created with the connectors.executor() function. It manages the order and the parallelization of the computations, when updating the data in a processing chain. If multiple connectors in a processing chain need to be computed, the executor of the connector, which started the computations, is used for all computations.

Parameters:	executor – an `Executor` instance, that can be created with the `connectors.executor()` function

set_parallelization(parallelization)¶

Specifies, if and how the execution of this connector can be parallelized. The choices are no parallelization, the execution in a separate thread and the execution in a separate process. This method specifies a hint, which level of parallelization is possible with the connector. If the executor of the connector, through which the computation is started, does not support the specified level, the next simpler one will be chosen. E.g. if a connector can be parallelized in a separate process, but the executor only allows threads or sequential execution, the connector will be executed in a separate thread.

Parameters:	parallelization – a flag from the `connectors.Parallelization` enum

class connectors.connectors.MacroInputConnector(instance, method)¶

A Connector-class that exports input connectors from an internal processing network to the API of the class, that encapsulates the network.

Parameters:	instance – the instance in which the method is replaced by this connector method – the unbound method, that is replaced by this connector

connect(connector)¶

Connects all exported input connectors to the given output.

Parameters:	connector – the output connector to which the exported connectors shall be connected
Returns:	the instance of which this connector has replaced a method

disconnect(connector)¶

Disconnects all exported input connectors from the given output.

Parameters:	connector – the output connector from which the exported connectors shall be disconnected
Returns:	the instance of which this connector has replaced a method

set_executor(executor)¶

Sets the executor, which handles the computations, when the data is retrieved through this connector. An executor can be created with the connectors.executor() function. It manages the order and the parallelization of the computations, when updating the data in a processing chain. If multiple connectors in a processing chain need to be computed, the executor of the connector, which started the computations, is used for all computations.

Parameters:	executor – an `Executor` instance, that can be created with the `connectors.executor()` function

set_laziness(laziness)¶

Configures the lazy execution of the connector. Normally the connectors are executed lazily, which means, that any computation is only started, when the result of a processing chain is requested. For certain use cases it is necessary to disable this lazy execution, though, so that the values are updated immediately as soon as new data is available. There are different behaviors for the (non) lazy execution, which are described in the connectors.Laziness enum.

Parameters:	laziness – a flag from the `connectors.Laziness` enum

set_parallelization(parallelization)¶

Specifies, if and how the execution of this connector can be parallelized. The choices are no parallelization, the execution in a separate thread and the execution in a separate process. This method specifies a hint, which level of parallelization is possible with the connector. If the executor of the connector, through which the computation is started, does not support the specified level, the next simpler one will be chosen. E.g. if a connector can be parallelized in a separate process, but the executor only allows threads or sequential execution, the connector will be executed in a separate thread.

Parameters:	parallelization – a flag from the `connectors.Parallelization` enum