Represents a user hardware pipeline usage session.
More...
|
|
| active_pipeline |
| |
|
| command_parser |
| |
|
| configuration |
| |
|
| id |
| |
|
| user_id |
| |
|
| setup_commands |
| |
|
| data_protocols |
| |
|
| telemetry_protocols |
| |
Represents a user hardware pipeline usage session.
This class is used to represent hardware pipeline reservations, which are specified by the reservation schedule. Session instances are managed by the SessionCoordinator, which is responsible for creating and destroying sessions as needed.
| def hwm.sessions.session.Session.__init__ |
( |
|
self, |
|
|
|
reservation_configuration, |
|
|
|
session_pipeline, |
|
|
|
command_parser |
|
) |
| |
Initializes the new session.
- Note
- The provided pipeline is not locked when it is passed in. self.start_session needs to be called to lock up the pipeline and perform other session setup tasks.
- Parameters
-
| reservation_configuration | A dictionary containing the configuration settings for the reservation associated with this session. |
| session_pipeline | The Pipeline that this session will use. |
| command_parser | The CommandParser that will be used to execute the session setup commands. |
| def hwm.sessions.session.Session._activate_session |
( |
|
self, |
|
|
|
setup_command_results |
|
) |
| |
|
private |
Marks the session as active.
This callback marks the session as active after its setup commands have been executed.
- Parameters
-
| setup_command_results | An array containing the results of the Session setup commands. |
- Returns
- Passes along the unmodified setup command results originally passed to this callback.
| def hwm.sessions.session.Session._run_setup_commands |
( |
|
self, |
|
|
|
pipeline_setup_commands_results |
|
) |
| |
|
private |
Runs the session setup commands.
This callback runs the session setup commands after the pipeline setup commands have all been executed successfully.
The session setup commands are responsible for putting the pipeline in the desired initial configuration based on
this session's associated reservation. For example, setup commands can be used by the pipeline user to set the
initial radio frequency.
- Note
- Session setup command failures will never trigger the errback chain because they are often recoverable with additional input from the user, unlike pipeline setup commands.
- Parameters
-
| pipeline_setup_commands_results | An array containing the results of the pipeline setup commands. May be None if there were no pipeline setup commands. |
- Returns
- Returns a DeferredList that will be fired with the results of the session setup commands. If this session doesn't specify any session setup commands, a pre-fired (with None) deferred will be returned.
| def hwm.sessions.session.Session._session_setup_error |
( |
|
self, |
|
|
|
failure |
|
) |
| |
|
private |
Cleans up after session-fatal errors and passes the failure along.
This callback handles some session-fatal errors that may have occured when setting up the session. For example, it
will be called if a pipeline setup command fails to execute. It cleans up after errors by rolling back any state
changes that may have been made (such as pipeline/hardware locks).
- Note
- Because session setup command errors aren't fatal, they won't trigger this callback.
-
This callback returns the original Failure after it has cleaned up the session. This will allow the session coordinator to detect that the session has failed and take the appropriate actions.
-
Because DeferredList wraps Failures in a FirstError instance, the failure will be flattened before being returned so it will always be consistent for the session coordinator.
- Parameters
-
| failure | A Failure object encapsulating the error (or FirstError if it was a DeferredList that failed). |
- Returns
- Returns the Failure object encapsulating the fatal exception.
| def hwm.sessions.session.Session.get_pipeline_telemetry_producer |
( |
|
self) | |
|
Returns the telemetry producer for the session's pipeline.
This method returns the PipelineTelemetryProducer belonging to the session's pipeline. This is typically used by the
telemetry protocol to regulate the production of pipeline telemetry.
- Returns
- Returns the PipelineTelemetryProducer instance belonging to the session's pipeline.
| def hwm.sessions.session.Session.is_active |
( |
|
self) | |
|
Indicates if the Session is active.
This property checks if the session is currently active. That is, if it has already completed its setup process and
is ready for user interaction.
- Returns
- Returns True if the Session is currently active and False otherwise.
| def hwm.sessions.session.Session.kill_session |
( |
|
self) | |
|
Terminates the session.
This method is called at the end of the session's reservation window and is responsible for freeing up any resources
being used by notifying the pipeline that the session has ended.
- Returns
- Returns a DeferredList containing the results of the device cleanup methods.
| def hwm.sessions.session.Session.register_data_protocol |
( |
|
self, |
|
|
|
data_protocol |
|
) |
| |
Registers the provided data protocol with the session.
This method is used to register a pipeline data protocol with the session. The session uses its registered data
protocols to route the pipeline output and input streams to and from the end user.
- Note
- Multiple data protocols can be registered to the session. Any data that the pipeline generates will be routed to all registered data protocols. This allows for simultaneous connections to the same session. However, if multiple data protocols attempt to write to the session at the same time the data may be interlaced randomly (because of the stream based nature of the system).
- Exceptions
-
- Parameters
-
| data_protocol | A Twisted Protocol class used to relay the pipeline's data stream to and from the session user. |
| def hwm.sessions.session.Session.register_telemetry_protocol |
( |
|
self, |
|
|
|
telemetry_protocol |
|
) |
| |
Registers the provided telemetry protocol with the session.
This method registers the supplied telemetry protocol with the session. The session will use this reference to pass
extra data (i.e. not the main pipeline output) from the pipeline to the end user. This data will consist of things
like extra data streams (e.g. a webcam feed) and live pipeline device state. This stream will be directed, with the
data flowing from the pipeline to the end user (through this session).
- Note
- This method allows multiple telemetry protocols to be registered with the session. Whenever the pipeline generates any telemetry, it will automatically be sent to each registered telemetry protocol.
- Exceptions
-
- Parameters
-
| telem_protocol | A Twisted Protocol class used to relay the pipeline's telemetry stream to the pipeline user. |
| def hwm.sessions.session.Session.start_session |
( |
|
self) | |
|
Sets up the session for use.
This method sets up a new session by:
- Reserving the pipeline hardware
- Registering the session with its pipeline
- Executing the pipeline setup commands
- Executing the session setup commands
- Activating the session
- Exceptions
-
| May | fire the errback callback chain on the returned deferred if there is a problem reserving the pipeline, registering the session, or executing the pipeline setup commands. This will cause the session coordinator to log the error and end the session. Session setup command errors don't generate session-fatal errors and are simply noted by the session coordinator. This is done because these errors will often be recoverable with additional input from the session user. |
- Note
- All of the pipeline setup commands will always be executed before any of the session setup commands are.
-
If a session-fatal error occurs, the self._session_setup_error callback will automatically clean up the session (e.g. freeing locks). Whatever calls this function (i.e. SessionCoordinator) doesn't need to worry about it.
- Returns
- Returns a deferred that will be fired with the results of session setup commands (an array containing the results for each setup command).
| def hwm.sessions.session.Session.write |
( |
|
self, |
|
|
|
input_data |
|
) |
| |
Writes the chunk of data to the pipeline.
This method writes the supplied chunk of data to the input stream of the pipeline associated with this session via
its write() method. This is one step in the process of getting the pipeline input data from the end user to the
pipeline's input device (typically a radio).
- Note
- Even though sessions can register multiple data protocols, only one protocol should write to this method at a time. This convention is followed by the default PipelineData protocol, which will only write to the session if that particular connection is allowed to do so.
- Parameters
-
| input_data | A data chunk of arbitrary size that is to be written to the pipeline's input stream. Normally, this comes from a Twisted protocol instance linked to the end user. |
| def hwm.sessions.session.Session.write_output |
( |
|
self, |
|
|
|
output_data |
|
) |
| |
Writes the provided data chunk to the registered data protocols.
This method writes the provided chunk of data (pipeline output) to all registered data protocols. This method will
typically be called by the pipeline associated with this session and facilitates passing pipeline output from the
Pipeline class to the end user.
- Note
- Whenever the pipeline generates any output data, this method will call the write_output() method for every data protocol registered to this session. The data passed to this method will be of arbitrary size.
- Parameters
-
| output_data | A chunk of pipeline output of arbitrary size. |
| def hwm.sessions.session.Session.write_telemetry |
( |
|
self, |
|
|
|
source_id, |
|
|
|
stream, |
|
|
|
timestamp, |
|
|
|
telemetry_datum, |
|
|
|
binary = False, |
|
|
|
extra_headers |
|
) |
| |
Writes the provided telemetry datum to the registered telemetry protocols.
This method passes the provided telemetry datum and headers to all registered telemetry protocols. It will be called
by this session's associated pipeline and facilitates the sending of pipeline telemetry (state, additional data
streams, etc.) from the pipeline (and its devices) to the pipeline user via the registered telemetry protocols
write_telemetry() methods.
- Note
- Because the telemetry stream uses HTTP, it's actually more of a packet stream than a true data stream (like the main pipeline stream). The Twisted protocol that sends the pipeline telemetry to the end user uses addressed HTTP packets to ensure that multiple unrelated data streams can be multi-plexed over the same socket without conflict. Thus, each call to this method will be with a complete "packet" of pipeline telemetry (i.e. a JSON state string or single webcam frame). What ever receives these HTTP packets on the other side of the socket will be responsible for assembling and displaying them in a coherent way.
- 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:
1.8.4 
