Class representing non-critical state of the session.
The data held here allows applications to reason about sessions in general but is not relevant to the runner or the core in general
Custom, application specific binary blob.
The type and value of this property is irrelevant as it is not inspected by plainbox at all. Reasonable applications will not make use of this property for storing large amounts of data. If you are tempted to do that, please redesign your application or propose changes to plainbox.
Application identifier
A string identifying the application that stored app_blob. It is recommended to use reverse domain names or UUIDs.
a set of flags that are associated with this session.
This set is persisted by persistent_save() and can be used to keep track of how the application wants to interpret this session state.
Intended usage is to keep track of “testing finished” and “results submitted” flags. Some flags are added as constants to this class.
id of the running job
Note
This property has a confusing name. It actually refers to job ID, not name.
This property should be updated to keep track of the name of the job that is being executed. When either plainbox or the machine it was running on crashes during the execution of a job this value should be preserved and can help the GUI to resume and provide an error message.
The property MUST be set before starting the job itself.
Class representing all state needed during a single program session.
This is the central glue/entry-point for applications. It connects user intents to the rest of the system / plumbing and keeps all of the state in one place.
The set of utility methods and properties allow applications to easily handle the lower levels of dependencies, resources and ready states.
SessionState has the following instance variables, all of which are currently exposed as properties.
Variables: |
|
---|
Add a new job to the session
Parameters: |
|
---|---|
Returns: | The job that was actually added or an existing, identical job if a perfect clash was silently ignored. |
Raises DependencyDuplicateError: | |
if a duplicate, clashing job definition is detected |
The new_job gets added to all the state tracking objects of the session. The job is initially not selected to run (it is not in the desired_job_list and has the undesired inhibitor).
The new_job may clash with an existing job with the same id. Unless both jobs are identical this will cause DependencyDuplicateError to be raised. Identical jobs are silently discarded.
Note
This method recomputes job readiness for all jobs
List of jobs that are on the “desired to run” list
This is a list, not a set, because the dependency solver algorithm retains as much of the original ordering as possible. Having said that, the actual order can differ widely (for instance, be reversed)
Provide the estimated duration of the jobs that have been selected to run in this session (maintained by calling update_desired_job_list).
Manual jobs have an arbitrary figure added to their runtime to allow for execution of the test steps and verification of the result.
Returns: | (estimate_automated, estimate_manual) |
---|
where estimate_automated is the value for automated jobs only and estimate_manual is the value for manual jobs only. These can be easily combined. Either value can be None if the value could not be calculated due to any job lacking the required estimated_duration field.
List of all known jobs.
Not necessarily all jobs from this list can be, or are desired to run. For API simplicity this variable is read-only, if you wish to alter the list of all jobs re-instantiate this class please.
Signal sent whenever a job is added to the session.
This signal is fired after on_job_state_map_changed()
Signal sent whenever a job is removed from the session.
This signal is fired after on_job_state_map_changed()
Signal fired after a job get changed (set)
This signal is fired each time a result is presented to the session.
This signal is fired after on_job_state_map_changed()
Signal fired after job_state_map is changed in any way.
This signal is always fired before any more specialized signals such as on_job_result_changed() and on_job_added().
This signal is fired pretty often, each time a job result is presented to the session and each time a job is added. When both of those events happen at the same time only one notification is sent. The actual state is not sent as it is quite extensive and can be easily looked at by the application.
List of jobs that were intended to run, in the proper order
The order is a result of topological sorting of the desired_job_list. This value is recomputed when change_desired_run_list() is called. It may be shorter than desired_run_list due to dependency errors.
Add or change a resource with the given id.
Resources silently overwrite any old resources with the same id.
Discard jobs that are selected by the given qualifier.
Parameters: | qualifier – A qualifier that selects jobs to be removed |
---|---|
Ptype qualifier: | |
IJobQualifier | |
Raises ValueError: | |
If any of the jobs selected by the qualifier is on the desired job list (or the run list) |
This function correctly and safely discards certain jobs from the job list. It also removes the associated job state (and referenced job result) and results (for jobs that were resource jobs)
Update the set of desired jobs (that ought to run)
This method can be used by the UI to recompute the dependency graph. The argument ‘desired_job_list’ is a list of jobs that should run. Those jobs must be a sub-collection of the job_list argument that was passed to the constructor.
It never fails although it may reduce the actual permitted desired_job_list to an empty list. It returns a list of problems (all instances of DependencyError class), one for each job that had to be removed.
Notice the specified test result and update readiness state.
This function updates the internal result collection with the data from the specified test result. Results can safely override older results. Results also change the ready map (jobs that can run) because of dependency relations.
Some results have deeper meaning, those are results for local and resource jobs. They are discussed in detail below:
Resource jobs produce resource records which are used as data to run requirement expressions against. Each time a result for a resource job is presented to the session it will be parsed as a collection of RFC822 records. A new entry is created in the resource map (entirely replacing any old entries), with a list of the resources that were parsed from the IO log.
Local jobs produce more jobs. Like with resource jobs, their IO log is parsed and interpreted as additional jobs. Unlike in resource jobs local jobs don’t replace anything. They cannot replace an existing job with the same id.