Chimera2 Sessions -- Take 2

Background

From the user perspective, Chimera2 is an application with a suite of tools. In any given session, there may be some user data (e.g., molecules and volumes) and some active tools (e.g., Reply Log and Command Line). One of the required functionality of Chimera2 is to be able to save the current state of the session, and then resume the session in the same state at the future time. This sounds simple enough, but there are some details that need to be explicitly enumerated, as not everyone will agree what consists "the state of the session".

From the developer side, we can distinguish a couple different types of data. Some data are the same for all sessions; for example, start-up preferences and the list of installed tools. Some data are different for different sessions; for example, the list of _active_ tools and the currently opened data files. Let's call the former "initial data" and the latter "session data". Chimera2's "state of the session" consists only of "session data". This means that if the user (a) saves a session, and then (b) changes his start-up preference (e.g., background color) and it was not explicitly overridden in a session (e.g., by changing the background color), then (c) on resumption, the session will use the new background color. Clearly, this may be unexpected for the user. We will need to define what data normally defined by "initial data" that should always be saved as "session data" so that these surprises are minimized. (The answer is not "all of them" because clearly the list of installed tools may change, and additions and deletions cannot be ignored.)

(Chimera2 data can be categorized as raw data, GUI data, and organizational data. Expound.)

The Problem

Ideally, when restoring a session, all data that is referenced by some other data has already been restored. Therefore all of dependencies need to be known by the saving code and there can be no circular dependencies. This avoids two-phase initialization, which is especially important for C++ objects.

Where is Session State?

All session state is accessible via a Session object. The session object has a registry of which of its attributes contain savable state and conform to the State API. Attributes that may contain nested data, and that data can use the same State API.

Examples of State

Session attributes:

• open models
• open tools
• running tasks
• scenes
• user colors
• user colormaps
• view (camera, lighting, clipping, etc.)
• selections (TODO)

Nested data:

• Tool GUI state
• molecules: atoms/bonds/residues & graphical state
• pseudobonds
• surfaces
• generic 3D graphics (e.g. STL)
• atom/bond annotations

Note that "tool" state may be in a session attribute rather than in the GUI instance.

Issues

• How to give dependencies for ordering session data?
  • naive data with back references are circular
  • may need to give before and after dependencies
• What is the granularity?
• Can we guarantee non-circular references?
• Can we provide a "simple" API for tools?

Part of the Solution

Saving protocol:

1. visit all session state and record:
   • what tool is responsible for the state
   • what data it refers to and
     • only referred to data needs to be named
2. save the list of used tools
3. serialize state
   • keep track of named data that was saved
4. confirm that all referred to data was saved

Restoring protocol:

1. Read the list of used tools
   • if installed tools are insufficient, then give user option to cancel or load tools
2. deserialze state inside block/unblock of triggers