Additional Topics¶
Modules¶
Modules are essentially plug-ins for Extensions. They provide a way of defining common and reusable functionality. An Extension can load zero or more modules during its creation. Loaded modules will then add their capabilities (see Capabilities) to those of the Extension. When calling code tries to access an attribute of an Extension the Extension doesn’t have, it will try to find the attribute among its loaded modules and will return that instead.
Note
Modules are themselves extensions, and can therefore load their own modules. Do not abuse this.
For example, calling code may wish to reboot an unresponsive device by calling
device.hard_reset()
, but the Device
in question does not have a
hard_reset
method; however the Device
has loaded netio_switch
module which allows to disable power supply over a network (say this device
is in a rack and is powered through such a switch). The module has
reset_power
capability (see Capabilities below) and so implements
hard_reset
. This will get invoked when device.hard_rest()
is called.
Note
Modules can only extend Extensions with new attributes; they cannot
override existing functionality. In the example above, if the
Device
has implemented hard_reset()
itself, then that will
get invoked irrespective of which modules it has loaded.
If two loaded modules have the same capability or implement the same method, then the last module to be loaded “wins” and its method will be invoke, effectively overriding the module that was loaded previously.
Specifying Modules¶
Modules get loaded when an Extension is instantiated by the extension loader. There are two ways to specify which modules should be loaded for a device.
Capabilities¶
Capabilities define the functionality that is implemented by an Extension, either within the Extension itself or through loadable modules. A capability is just a label, but there is an implied contract. When an Extension claims to have a particular capability, it promises to expose a particular set of functionality through a predefined interface.
Currently used capabilities are described below.
Note
Since capabilities are basically random strings, the user can always define their own; and it is then up to the user to define, enforce and document the contract associated with their capability. Below, are the “standard” capabilities used in WA.
Note
The method signatures in the descriptions below show the calling signature (i.e. they’re omitting the initial self parameter).
active_cooling¶
Intended to be used by devices and device modules, this capability implies that the device implements a controllable active cooling solution (e.g. a programmable fan). The device/module must implement the following methods:
- start_active_cooling()
- Active cooling is started (e.g. the fan is turned on)
- stop_active_cooling()
- Active cooling is stopped (e.g. the fan is turned off)
reset_power¶
Intended to be used by devices and device modules, this capability implies that the device is capable of performing a hard reset by toggling power. The device/module must implement the following method:
- hard_reset()
- The device is restarted. This method cannot rely on the device being responsive and must work even if the software on the device has crashed.
flash¶
Intended to be used by devices and device modules, this capability implies that the device can be flashed with new images. The device/module must implement the following method:
- flash(image_bundle=None, images=None)
image_bundle
is a path to a “bundle” (e.g. a tarball) that contains all the images to be flashed. Which images go where must also be defined within the bundle.images
is a dict mapping image destination (e.g. partition name) to the path to that specific image. Bothimage_bundle
andimages
may be specified at the same time. If there is overlap between the two,images
wins and its contents will be flashed in preference to theimage_bundle
.