Represents and provides access to a hardware pipeline.
More...
|
|
| device_manager |
| |
|
| command_parser |
| |
|
| pipeline_configuration |
| |
|
| id |
| |
|
| mode |
| |
|
| setup_commands |
| |
|
| produce_telemetry |
| |
|
| current_session |
| |
|
| input_device |
| |
|
| output_device |
| |
|
| devices |
| |
|
| services |
| |
|
| active_services |
| |
|
| telemetry_producer |
| |
Represents and provides access to a hardware pipeline.
This class provides an interface to the hardware pipeline and associated hardware devices.
| def hwm.hardware.pipelines.pipeline.Pipeline.__init__ |
( |
|
self, |
|
|
|
pipeline_configuration, |
|
|
|
device_manager, |
|
|
|
command_parser |
|
) |
| |
Initializes the pipeline with the supplied configuration.
- Exceptions
-
| May | pass on any exceptions raised during the pipeline setup procedure (see _setup_pipeline()). |
- Parameters
-
| pipeline_configuration | A dictionary containing the configuration settings for this pipeline. This is supplied by the pipeline manager and is loaded from the pipeline configuration file. |
| device_manager | A reference to the DeviceManager that will be used to load the pipeline hardware. |
| command_parser | A reference to the CommandParser that will be used to run pipeline setup commands. |
| def hwm.hardware.pipelines.pipeline.Pipeline._load_pipeline_devices |
( |
|
self) | |
|
|
private |
Loads the pipeline's devices and performs additional validations on the pipeline's device configuration.
This method performs additional initial validations on the pipeline and does some initial setup such as driver
registration. It will not check for schema errors because the PipelineManager should have already checked the
pipeline configuration schema by the time this pipeline was initialized.
Currently, this method checks for the following:
- Multiple pipeline input devices
- Multiple pipeline output devices
- Non-existent pipeline devices
- Duplicate pipeline devices
In addition, it will also register the pipeline with each of its devices.
- Exceptions
-
| def hwm.hardware.pipelines.pipeline.Pipeline._set_active_services |
( |
|
self) | |
|
|
private |
Sets the pipeline's active services.
This method sets the active services for the pipeline based on the provided session's configuration. For example, if
the pipeline's devices offer multiple "tracker" services, this method will set the active one based on what's
specified in the session configuration.
- Note
- The active_services dictionary gets reset every time a session is registered (because which services are active always depends on the session configuration). This method should only be called from self.register_session().
-
Only one service per service type can be active at any given time.
- Exceptions
-
| Raises | ServiceInvalid if the session configuration specifies a service that isn't registered to the pipeline or if it specifies a service type that isn't available to the pipeline. |
| def hwm.hardware.pipelines.pipeline.Pipeline.cleanup_after_session |
( |
|
self) | |
|
Cleans up the pipeline and its devices after the session using the pipeline has expired.
This method is called after a session has expired and is responsible for putting the pipeline and its devices back
into an "idle" state in preparation for the next session.
- Returns
- Returns a DeferredList containing the results of each device cleanup method wrapped in a deferred (if it's not already).
| def hwm.hardware.pipelines.pipeline.Pipeline.free_pipeline |
( |
|
self) | |
|
Frees the pipeline.
This method is used to free the hardware pipeline. This typically occurs at the conclusion of a usage session, but
it can also occur in the event that a session that is currently using the pipeline experiences a fatal error.
- Note
- This method will only unlock hardware devices if the pipeline is reserved. This will prevent the pipeline from unlocking devices that are being used by other pipelines that share some of the same hardware devices.
| def hwm.hardware.pipelines.pipeline.Pipeline.get_device |
( |
|
self, |
|
|
|
device_id |
|
) |
| |
Returns the driver for the specified device.
- Exceptions
-
| May | throw DeviceNotFound if the specified device is not present in the pipeline. |
- Parameters
-
| device_id | The ID of the device driver to load. |
- Returns
- Returns a Driver instance for the specified device.
| def hwm.hardware.pipelines.pipeline.Pipeline.is_active |
( |
|
self) | |
|
Indicates if the pipeline is currently active.
This property checks if the pipeline is active. That is to say, whether or not it is being used by a session. This
method is commonly used to determine if a given driver should write data to the pipeline or not (if the pipeline is
registered with the device).
- Note
- Because pipelines can only ever be used by a single session at a time, an active pipeline can also be considered locked. This differs from drivers, which can be active and unlocked at the same time (in the case of concurrent access devices).
- Returns
- Returns True if the pipeline is currently being used and False otherwise.
| def hwm.hardware.pipelines.pipeline.Pipeline.load_service |
( |
|
self, |
|
|
|
service_type |
|
) |
| |
Returns the active service for the specified service type.
This method queries the pipeline's active service dictionary and returns the callable for the specified service
type. Drivers will use this method to load services when sessions begin.
- Exceptions
-
| Raises | ServiceTypeNotFound if there are currently not any active services for the specified type. |
- Note
- The registered services that should be active at any given time are specified by the reservation schedule and set in self._set_active_services() at the beginning of each session.
- Parameters
-
| service_type | A string indicating the desired service type. |
- Returns
- Returns the service callable.
| def hwm.hardware.pipelines.pipeline.Pipeline.prepare_for_session |
( |
|
self, |
|
|
|
session |
|
) |
| |
Prepares the Pipeline and its devices for a new session.
This method gives pipelines and devices a chance to perform any setup actions required for a new session before the
user is given control.
- Note
- This step must occur before any pipeline and session setup commands are run so that any devices that the setup commands may be addressed to will be completely setup and ready to receive commands.
- Parameters
-
| session | The new session that is being set up. |
- Returns
- If successful, this will return a deferred pre-fired with "True." If any of the device setup methods throw an exception, it will trigger the errback chain on the return deferred.
| def hwm.hardware.pipelines.pipeline.Pipeline.register_service |
( |
|
self, |
|
|
|
service |
|
) |
| |
Registers services with the pipeline.
This method registers the specified service with the pipeline. Unsurprisingly, services offer some service to the
pipeline and its devices. If another device in the pipeline knows which interface a particular service implements,
it can query the pipeline for the service callable and use it via the methods defined in the service's interface.
- Note
- Services may define their own interfaces not derived from one of the standard ones but devices won't be able to use them unless they were specifically designed to be able to do so.
-
Pipelines may have multiple services of the same type registered to them. During the session startup process, the Pipeline will configure which service should be active for each service type. It is this service that will be returned when a device queries for a service of that type. All available services are stored in self.services whereas the active services are stored in self.active_services.
- Exceptions
-
- Parameters
-
| service | A callable (typically a class) that provides an interface for interacting with the service. |
| def hwm.hardware.pipelines.pipeline.Pipeline.register_session |
( |
|
self, |
|
|
|
session |
|
) |
| |
Registers the provided session with this pipeline.
This method registers the session with the pipeline for the purpose of sending data such as the main pipeline output
and pipeline telemetry to the session (and to the data/telemetry protocols in turn). It also calls a method that
enables the session's active services.
- Note
- Only one session can be registered to the pipeline at a time. This is because pipelines can only be used by a single session (or reservation) at a time. Because the session coordinator ends old sessions before it creates new ones, this shouldn't be a problem for back to back reservations.
- Exceptions
-
| Raises | SessionAlreadyRegistered in the event that a session is registered to a pipeline that already has a registered session. Sessions must be deregistered before a new one can be registered. |
| May | pass on ServiceInvalid exceptions if the session configuration specifies an invalid service (i.e. a non-existent service or service type). |
- Parameters
-
| session | The Session instance that should currently be associated with the pipeline. |
| def hwm.hardware.pipelines.pipeline.Pipeline.reserve_pipeline |
( |
|
self) | |
|
Locks the pipeline and its hardware.
This method is used primarily by sessions to ensure that a pipeline and its hardware are never used concurrently
by two different sessions (unless a device is configured to allow for concurrent access). A session will reserve its
pipeline as the session is being set up.
- Note
- If a pipeline can not be reserved because one or more of its hardware devices is currently reserved, it will rollback any reservations that it may have acquired already.
- Exceptions
-
| Raises | PipelineInUse if the pipeline (or any of its hardware devices) is currently being used and can't be reserved. |
| def hwm.hardware.pipelines.pipeline.Pipeline.run_setup_commands |
( |
|
self, |
|
|
|
session_preparation_results |
|
) |
| |
Runs the pipeline setup commands.
This method runs the pipeline setup commands, which are responsible for putting the pipeline in its intended state
before use by a session.
- Parameters
-
| session_preparation_results | The results of the prepare_for_session() call, should always be True (otherwise the errback chain would have triggered). |
- Returns
- If successful, this method will return a DeferredList containing the results of the pipeline setup commands. If any of the commands fail additional validations by the command parser, a pre-fired failed deferred will be returned. Finally, if this pipeline doesn't have any setup commands None will be returned via a pre-fired successful deferred.
| def hwm.hardware.pipelines.pipeline.Pipeline.write |
( |
|
self, |
|
|
|
input_data |
|
) |
| |
Writes the specified data chunk to the pipeline's input device.
This method writes the provided data chunk to the pipeline's input device, if it has one. If the pipeline doesn't
have an input device, the data will simply be dropped and ignored. Typically, this data will come from the Session
that is currently using this pipeline.
- Note
- The specified data chunk will be passed to the pipeline's input device via its write() method.
- Parameters
-
| input_data | A data chunk of arbitrary size that is to be written to the pipeline's input device. |
| def hwm.hardware.pipelines.pipeline.Pipeline.write_output |
( |
|
self, |
|
|
|
output_data |
|
) |
| |
Pushes the specified data to the pipeline's output data stream.
This method writes the specified data chunk to the pipeline's main data stream by passing it to the registered
session's write_output() methods.
- Note
- Typically, only a single device in a pipeline should make calls to this method (the pipeline's output device). This behavior is encouraged by the default Driver interface (Driver.write_output()). If this convention isn't followed, the pipeline output may end up getting jumbled.
-
If no session is currently registered to the pipeline any data passed to this method will be discarded.
- Todo:
- The pipeline data output stream should use a push producer to keep memory consumption to a minimum. This push producer would write the pipeline output directly to a file and then read from that file as required.
- Parameters
-
| output_data | A data chunk of arbitrary size that is to be written to the pipeline's main output stream. |
| def hwm.hardware.pipelines.pipeline.Pipeline.write_telemetry |
( |
|
self, |
|
|
|
source_id, |
|
|
|
stream, |
|
|
|
timestamp, |
|
|
|
telemetry_datum, |
|
|
|
binary = False, |
|
|
|
extra_headers |
|
) |
| |
Passes the provided telemetry datum to the session registered to this pipeline.
Sends the provided telemetry datum and its headers to the session currently using this pipeline. The session will
be responsible for routing the telemetry to its appropriate destination (typically a telemetry protocol). This
method is normally called by the pipeline's output device.
- Note
- If no session is currently associated with the pipeline, or if the pipeline's telemetry output is currently being throttled, calls to this method will just be ignored (and the data discarded). As a result, it is not guaranteed that data passed to this method will ever reach the end user.
- Parameters
-
| source_id | The ID of the device or pipeline that generated the telemetry datum. |
| stream | A string identifying which of the device's telemetry streams the datum should be associated with. |
| timestamp | A unix timestamp specifying when the telemetry point was assembled. |
| telemetry_datum | The actual telemetry datum. Can take many forms (e.g. a dictionary or binary webcam image). |
| binary | Whether or not the telemetry payload consists of binary data. If set to true, the data will be encoded before being sent to the user. |
| **extra_headers | A dictionary containing extra keyword arguments that should be included as additional headers when sending the telemetry datum. |
The documentation for this class was generated from the following file:
- hwm/hardware/pipelines/pipeline.py
1.8.4 
