plainbox.impl.session.legacy
– Legacy suspend/resume API¶
-
class
plainbox.impl.session.legacy.
ISessionStateLegacyAPI
[source]¶ Bases:
object
Interface describing legacy parts of the SessionState API.
-
jobs_io_log_dir
¶ pathname of the jobs IO logs directory
This is not None only between calls to open() / close().
-
open
¶ Open session state for running jobs.
This function creates the cache directory where jobs can store their data. See: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
-
previous_session_file
()[source]¶ Check the filesystem for previous session data Returns the full pathname to the session file if it exists
-
session_data_filename
= 'session.json'¶
-
session_dir
¶ pathname of a temporary directory for this session
This is not None only between calls to open() / close().
-
-
plainbox.impl.session.legacy.
SessionStateLegacyAPI
¶ alias of
SessionStateLegacyAPICompatImpl
-
class
plainbox.impl.session.legacy.
SessionStateLegacyAPICompatImpl
(job_list)[source]¶ Bases:
plainbox.impl.session.state.SessionState
,plainbox.impl.session.legacy.ISessionStateLegacyAPI
Compatibility wrapper to use new suspend/resume implementation via the original (legacy) suspend/resume API.
This subclass of SessionState implements the ISessionStateLegacyAPI interface thus allowing applications to keep using suspend/resume as they did before, without adjusting their code.
Variables: - _manager – Instance of SessionManager (this is a bit insane because the manager actually knows about the session too)
- _commit_hint – Either None or a set of flags (strings) that determine what kind of actions should take place before the next time the ‘manager’ property gets accessed. This is used to implement lazy decision on how to map the open/resume/clean methods onto the SessionManager API
-
add_job
(new_job, recompute=True)¶ Add a new job to the session.
Parameters: - new_job – The job being added
- recompute – If True, recompute readiness inhibitors for all jobs.
You should only set this to False if you’re adding
a number of jobs and will otherwise ensure that
_recompute_job_readiness()
gets called before session state users can see the state again.
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
Deprecated since version 0.9: use the add_unit() method instead
-
add_unit
(new_unit, recompute=True)¶ Add a new unit to the session.
Parameters: - new_unit – The unit being added
- recompute – If True, recompute readiness inhibitors for all jobs.
You should only set this to False if you’re adding
a number of jobs and will otherwise ensure that
_recompute_job_readiness()
gets called before session state users can see the state again.
Returns: The unit that was actually added or an existing, identical unit if a perfect clash was silently ignored.
Raises DependencyDuplicateError: if a duplicate, clashing job definition is detected
Note
The following applies only to newly added job units:
The new_unit gets added to all the state tracking objects of the session. The job unit is initially not selected to run (it is not in the desired_job_list and has the undesired inhibitor).
The new_unit 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 unless the recompute=False argument is used. Recomputing takes a while so if you want to add a lot of units consider setting that to False and only recompute at the last call.
-
desired_job_list
¶ 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)
-
get_certification_status_map
(outcome_filter=('fail', ), certification_status_filter=('blocker', ))¶ Get a map of jobs that have a specific certification blocker status.
Filter the Job state map to only return items with given outcomes and certification statuses.
Parameters: - outcome_filter – Only consider job results with those outcome values
- certification_status_filter – Only consider jobs with those certification status values
Returns: a Job state map only containing job with a given outcome and certification status value.
-
get_estimated_duration
(manual_overhead=30.0)¶ Estimate the total duration of the session.
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.
-
get_outcome_stats
()¶ Process the JobState map to get stats about the job outcomes.
Returns: a mapping of “outcome”: “total” key/value pairs Note
Only the outcomes seen during this session are reported, not all possible values (such as crash, not implemented, ...).
-
job_list
¶ 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.
-
job_state_map
¶ Map from job id to JobState associated with each job.
-
jobs_io_log_dir
¶ pathname of the jobs IO logs directory
This is not None only between calls to open() / close().
-
manager
¶
-
metadata
¶ meta-data object associated with this session state.
-
on_job_added
¶ Basic signal that supports arbitrary listeners.
While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the
plainbox.vendor.morris
module for details.Attr _name: Name of the signal, typically accessed via name()
.Attr _listeners: List of signal listeners. Each item is a tuple (listener, pass_signal)
that encodes how to call the listener.
-
on_job_removed
¶ Basic signal that supports arbitrary listeners.
While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the
plainbox.vendor.morris
module for details.Attr _name: Name of the signal, typically accessed via name()
.Attr _listeners: List of signal listeners. Each item is a tuple (listener, pass_signal)
that encodes how to call the listener.
-
on_job_result_changed
¶ Basic signal that supports arbitrary listeners.
While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the
plainbox.vendor.morris
module for details.Attr _name: Name of the signal, typically accessed via name()
.Attr _listeners: List of signal listeners. Each item is a tuple (listener, pass_signal)
that encodes how to call the listener.
-
on_job_state_map_changed
¶ Basic signal that supports arbitrary listeners.
While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the
plainbox.vendor.morris
module for details.Attr _name: Name of the signal, typically accessed via name()
.Attr _listeners: List of signal listeners. Each item is a tuple (listener, pass_signal)
that encodes how to call the listener.
-
on_unit_added
¶ Basic signal that supports arbitrary listeners.
While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the
plainbox.vendor.morris
module for details.Attr _name: Name of the signal, typically accessed via name()
.Attr _listeners: List of signal listeners. Each item is a tuple (listener, pass_signal)
that encodes how to call the listener.
-
on_unit_removed
¶ Basic signal that supports arbitrary listeners.
While this class can be used directly it is best used with the helper decorator Signal.define on a function or method. See the documentation for the
plainbox.vendor.morris
module for details.Attr _name: Name of the signal, typically accessed via name()
.Attr _listeners: List of signal listeners. Each item is a tuple (listener, pass_signal)
that encodes how to call the listener.
-
previous_session_file
()[source]¶ Check the filesystem for previous session data Returns the full pathname to the session file if it exists
-
remove_unit
(unit, *, recompute=True)¶ Remove an existing unit from the session.
Parameters: - unit – The unit to remove
- recompute – If True, recompute readiness inhibitors for all jobs.
You should only set this to False if you’re adding
a number of jobs and will otherwise ensure that
_recompute_job_readiness()
gets called before session state users can see the state again.
Note
This method recomputes job readiness for all jobs unless the recompute=False argument is used. Recomputing takes a while so if you want to add a lot of units consider setting that to False and only recompute at the last call.
-
resource_map
¶ Map from resource id to a list of resource records.
-
run_list
¶ 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.
-
session_data_filename
= 'session.json'¶
-
session_dir
¶ pathname of a temporary directory for this session
This is not None only between calls to open() / close().
-
set_resource_list
(resource_id, resource_list)¶ Add or change a resource with the given id.
Resources silently overwrite any old resources with the same id.
-
trim_job_list
(qualifier)¶ 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)
-
unit_list
¶ List of all known units.
-
update_desired_job_list
(desired_job_list)¶ 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.
-
update_job_result
(job, result)¶ 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.