plainbox.impl.session.manager
– manager for sessions¶
This module contains glue code that allows one to create and manage sessions
and their filesystem presence. It allows
SessionState
to be de-coupled
from SessionStorageRepository
,
SessionStorage
,
SessionSuspendHelper
and SessionResumeHelper
.
-
class
plainbox.impl.session.manager.
SessionManager
(*args, **kwargs)[source]¶ Bases:
plainbox.impl.pod.POD
Manager class for coupling SessionStorage with SessionState.
This class allows application code to manage disk state of sessions. Using the
checkpoint()
method applications can create persistent snapshots of theSessionState
associated with eachSessionManager
.-
add_device_context
(context)[source]¶ Add a device context to the session manager
Parameters: context – The SessionDeviceContext
to add.Raises: ValueError – If the context is already in the session manager or the device represented by that context is already present in the session manager. This method fires the
on_device_context_added()
signal
-
add_local_device_context
()[source]¶ Create and add a SessionDeviceContext that describes the local device.
The local device is always the device executing plainbox. Other devices may execute jobs or parts of plainbox but they don’t need to store or run the full plainbox code.
-
as_dict
() → dict¶ Return the data in this POD as a dictionary.
Note
UNSET values are not added to the dictionary.
-
as_tuple
() → tuple¶ Return the data in this POD as a tuple.
Order of elements in the tuple corresponds to the order of field declarations.
-
checkpoint
()[source]¶ Create a checkpoint of the session.
After calling this method you can later reopen the same session with
SessionManager.load_session()
.
-
classmethod
create
(repo=None, prefix='pbox-')[source]¶ Create an empty session manager.
This method creates an empty session manager. This is the most generic API that allows applications to freely work with any set of devices.
Typically applications will use the
add_device_context()
method to add additional context objects at a later time. This method creates and populates the session storage with all of the well known directories (usingWellKnownDirsHelper.populate()
).Parameters: repo – If specified then this particular repository will be used to create the storage for this session. If left out, a new repository is constructed with the default location. Ptype repo: SessionStorageRepository
.Returns: fresh SessionManager
instance
-
create_exporter
(exporter_id, option_list=(), strict=True)[source]¶ Create an exporter object with the specified name and options.
Parameters: - exporter_id – Identifier of the exporter unit (which must have been loaded
into the session device context of the first device). For
backwards compatibility this can also be any of the legacy
identifiers
tar
,html
,json
,text
orxlsx
. - option_list – (optional) A list of options to pass to the exporter. Each option is a string. Some strings may be of form ‘key=value’ but those are handled by each exporter separately. By default an empty tuple is used so no special options are enabled.
- strict – (optional) Strict mode, in this mode
option_list
must not contain any options that are unrecognized by the exporter. Since many options (but not all) are shared among various exporters, using non-strict mode might make it easier to use a single superset of options to all exporters and let them silently ignore those that they don’t understand.
Raises: LookupError – If the exporter identifier cannot be found. Note that this might indicate that appropriate provider has not been loaded yet.
Returns: A ISessionStateExporter instance with appropriate configuration.
- exporter_id – Identifier of the exporter unit (which must have been loaded
into the session device context of the first device). For
backwards compatibility this can also be any of the legacy
identifiers
-
classmethod
create_with_state
(state, repo=None)[source]¶ Create a session manager by wrapping existing session state.
This method populates the session storage with all of the well known directories (using
WellKnownDirsHelper.populate()
)Parameters: - stage – A pre-existing SessionState object.
- repo – If specified then this particular repository will be used to create the storage for this session. If left out, a new repository is constructed with the default location.
Ptype repo: Returns: fresh
SessionManager
instance
-
classmethod
create_with_unit_list
(unit_list=None, repo=None)[source]¶ Create a session manager with a fresh session.
This method populates the session storage with all of the well known directories (using
WellKnownDirsHelper.populate()
)Parameters: - unit_list – If specified then this will be the initial list of units known by the session state object.
- repo – If specified then this particular repository will be used to create the storage for this session. If left out, a new repository is constructed with the default location.
Ptype repo: Returns: fresh
SessionManager
instance
-
default_device_context
¶ The default (first) session device context if available
In single-device sessions this is the context that is used to execute every single job definition. Applications that use multiple devices must access and use the context list directly.
-
destroy
()[source]¶ Destroy all of the filesystem artifacts of the session.
This basically calls
remove()
-
device_context_list
¶ A list of session device context objects
Note
You must not modify this field directly.
This is not enforced but please use the
add_device_context()
orremove_device_context()
if you want to manipulate the list. Currently you cannot reorder the list of context objects.- Side effects of assign filters:
- type-checked (value must be of type list)
- type-checked sequence (items must be of type SessionDeviceContext)
- constant (read-only after initialization)
-
exporter_map
¶ Map from exporter id to the corresponding exporter unit.
-
field_list
= [<Field name:'device_context_list'>, <Field name:'storage'>, <Field name:'test_plans'>]¶
-
classmethod
get_throwaway_manager
(provider_list=None)[source]¶ Create a temporary session manager.
Parameters: provider_list – (optional) A list of providers to put into the session manager. By default all known providers are added. You can use this argument to customize the behaviour beyond defaults. Returns: A new SessionManager object that will be destroyed when the context manager is left. This method can be used to create a throw-away session manager which is not really meant for running jobs but can be useful to access exporters and other objects stored in providers.
-
classmethod
load_session
(unit_list, storage, early_cb=None, flags=None)[source]¶ Load a previously checkpointed session.
This method allows one to re-open a session that was previously created by
SessionManager.checkpoint()
Parameters: - unit_list – List of all known units. This argument is used to reconstruct the
session from a dormant state. Since the suspended data cannot
capture implementation details of each unit reliably, actual units
need to be provided externally. Unlike in
create_session()
this list really needs to be complete, it must also include any generated units. - storage – The storage that should be used for this particular session. The storage object holds references to existing directories in the file system. When restoring an existing dormant session it is important to use the correct storage object, the one that corresponds to the file system location used be the session before it was saved.
- 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 callbacks on the new session before this method
call returns. The callback accepts one argument, session, which is
being resumed. This is being passed directly to
plainbox.impl.session.resume.SessionResumeHelper.resume()
- flags – An optional set of flags that may influence the resume process. Currently this is an internal implementation detail and no “public” flags are provided. Passing None here is a safe equvalent of using this API before it was introduced.
Ptype storage: Raises: Anything that can be raised by
load_checkpoint()
andresume()
Returns: Fresh instance of
SessionManager
- unit_list – List of all known units. This argument is used to reconstruct the
session from a dormant state. Since the suspended data cannot
capture implementation details of each unit reliably, actual units
need to be provided externally. Unlike in
-
namedtuple_cls
¶ alias of
SessionManager
-
on_device_context_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_device_context_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_test_plans_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.
-
remove_device_context
(context)[source]¶ Remove an device context from the session manager
Parameters: unit – The SessionDeviceContext
to remove.This method fires the
on_device_context_removed()
signal
-
state
¶ SessionState
associated with this manager
-
storage
¶ A SesssionStorage instance
- Side effects of assign filters:
- type-checked (value must be of type SessionStorage)
- constant (read-only after initialization)
-
test_plans
¶ Test plans that this session is processing.
This field contains a tuple of test plans that are active in the session. Any changes here are propagated to each device context participating in the session. This in turn makes all of the overrides defined by those test plans effective.
Note
Currently there is no facitly that would allow to use this field to drive test execution. Such facility is likely to be added later.
- Side effects of assign filters:
- type-checked (value must be of type tuple)
- type-checked sequence (items must be of type TestPlanUnit)
- unique elements (sequence elements cannot repeat)
-
-
class
plainbox.impl.session.manager.
WellKnownDirsHelper
(*args, **kwargs)[source]¶ Bases:
plainbox.impl.pod.POD
Helper class that knows about well known directories for SessionStorage.
This class simply gets rid of various magic directory names that we associate with session storage. It also provides a convenience utility method
populate()
to create all of those directories, if needed.-
all_directories
¶ a list of all well-known directories
-
as_dict
() → dict¶ Return the data in this POD as a dictionary.
Note
UNSET values are not added to the dictionary.
-
as_tuple
() → tuple¶ Return the data in this POD as a tuple.
Order of elements in the tuple corresponds to the order of field declarations.
-
field_list
= [<Field name:'storage'>]¶
-
io_log_pathname
¶ full path of the directory where per-job IO logs are stored
-
namedtuple_cls
¶ alias of
WellKnownDirsHelper
-
populate
()[source]¶ Create all of the well known directories that are expected to exist inside a freshly created session storage directory
-
storage
¶ SessionStorage associated with this helper
- Side effects of assign filters:
- constant (read-only after initialization)
- type-checked (value must be of type SessionStorage)
-