plainbox.impl.session.resume – session resume handling

This module contains classes that can resume a dormant session from a binary representation. See docs for the suspend module for details.

The resume logic provides a compromise between usefulness and correctness so two assumptions are made:

  • We assume that a checksum of a job changes when their behavior changes. This way we can detect when job definitions were updated after suspending but before resuming.

  • We assume that software and hardware may change while the session is suspended but this is not something that framework (PlainBox) is concerned with. Applications should provide job definitions that are capable of detecting this and acting appropriately.

    This is true since the user may install additional packages or upgrade existing packages. The user can also add or remove pluggable hardware. Lastly actual machine suspend (or hibernate) and resume may cause alterations to the hardware as it is visible from within the system. In any case the framework does not care about this.

exception plainbox.impl.session.resume.CorruptedSessionError[source]

Exception raised when SessionResumeHelper cannot decode the session byte stream. This exception will be raised with additional context that captures the actual underlying cause. Having this exception class makes it easier to handle resume errors.

exception plainbox.impl.session.resume.IncompatibleJobError[source]

Exception raised when SessionResumeHelper detects that the set of jobs it knows about is incompatible with what was saved before.

exception plainbox.impl.session.resume.IncompatibleSessionError[source]

Exception raised when SessionResumeHelper comes across malformed or unsupported data that was (presumably) produced by SessionSuspendHelper

class plainbox.impl.session.resume.ResumeDiscardQualifier(jobs_repr)[source]

A job qualifier that designates jobs that should be removed after doing a session resume.

get_simple_match(job)[source]
exception plainbox.impl.session.resume.SessionResumeError[source]

Base class for exceptions that can be raised when attempting to resume a dormant session.

class plainbox.impl.session.resume.SessionResumeHelper(job_list)[source]

Helper class for implementing session resume feature.

This class is a facade that does enough of the resume process to know which version is being resumed and delegate the rest of the process to an appropriate, format specific, resume class.

resume(data, early_cb=None)[source]

Resume a dormant session.

Parameters:
  • data – Bytes representing the dormant session
  • early_cb – A callback that allows the caller to “see” the session object early, before the bulk of resume operation happens. This method can be used to register signal listeners on the new session before this method call returns. The callback accepts one argument, session, which is being resumed.
Returns:

resumed session instance

Return type:

SessionState

This method validates the representation of a dormant session and re-creates an identical SessionState instance. It can fail in multiple ways, some of which are a part of normal operation and should always be handled (IncompatibleJobError and IncompatibleJobError). Applications may wish to capture SessionResumeError as a generic base exception for all the possible problems.

Raises:
  • CorruptedSessionError – if the representation of the session is corrupted in any way
  • IncompatibleSessionError – if session serialization format is not supported
  • IncompatibleJobError – if serialized jobs are not the same as current jobs
class plainbox.impl.session.resume.SessionResumeHelper1(job_list)[source]

Helper class for implementing session resume feature

This class works with data constructed by SessionSuspendHelper1 which has been pre-processed by SessionResumeHelper (to strip the initial envelope).

Due to the constraints of what can be represented in a suspended session, this class cannot work in isolation. It must operate with a list of know jobs.

Since (most of the) jobs are being provided externally (as they represent the non-serialized parts of checkbox or other job providers) several failure modes are possible. Those are documented in resume()

resume_json(json_repr, early_cb=None)[source]

Resume a SessionState object from the JSON representation.

This method is called by resume() after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.

class plainbox.impl.session.resume.SessionResumeHelper2(job_list)[source]

Helper class for implementing session resume feature

This class works with data constructed by SessionSuspendHelper2 which has been pre-processed by SessionResumeHelper (to strip the initial envelope).

Due to the constraints of what can be represented in a suspended session, this class cannot work in isolation. It must operate with a list of know jobs.

Since (most of the) jobs are being provided externally (as they represent the non-serialized parts of checkbox or other job providers) several failure modes are possible. Those are documented in resume()

class plainbox.impl.session.resume.SessionResumeHelper3(job_list)[source]

Helper class for implementing session resume feature

This class works with data constructed by SessionSuspendHelper3 which has been pre-processed by SessionResumeHelper (to strip the initial envelope).

Due to the constraints of what can be represented in a suspended session, this class cannot work in isolation. It must operate with a list of know jobs.

Since (most of the) jobs are being provided externally (as they represent the non-serialized parts of checkbox or other job providers) several failure modes are possible. Those are documented in resume()

Previous topic

plainbox.impl.session.manager – manager for sessions

Next topic

plainbox.impl.session.state – session state handling

This Page