Re: Session Management Proposal



Hi,

I've incorporated most things that have been discussed so
far into the spec.  It's attached in docbook xml and online as html at
http://www.grokthecruft.org/dsme/.  Improvements will be appreciated.

I did add something to the spec about session managers reporting to
their clients what shutdown modes are available.

Having the session manager set properties (opposed to having clients
set properties) is bit of an ugly situation because the XSMP (and
SMlib) never planned for it to happen.  For one thing, there is no
client notification when properties are set, which means if clients
want to watch properties they are going to have to resort to polling. If a client wants to watch some properties it basically has to do
something along the lines of:

/* in a timeout that runs every once in a while */
/* queue a request for the session manager to
  send all the properties that belong to the client back to the
  client */
SmcGetProperties (..., properties_received_callback, ...);
...
/* exit timeout, do other things, and wait for
  properties_received_callback () to be invoked */
...

/* later in properties_received_callback */

for each property in set of received properties:
  if property is being watched
     and property's value has changed:
        notify property handler that property has changed

Sending all the properties of a client over and over again for
as long as the client is connected to the session manager doesn't sound
like a nice idea at all.  Luckily, the property we're concerned with
right now, _DSME_AvailableShutdownModes, isn't something that's likely
to change over the lifetime of the session manager, so there shouldn't
be any need for the clients to worry about watching the property. What it does mean is that we should avoid having the session manager
set properties that are subject to change after clients initially
fetch them.
--Ray


<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
<article id="index">
  <articleinfo>
    <title>Desktop Session Management Extensions</title>
    <releaseinfo>Version 0.6</releaseinfo>
    <date>31 December 2003</date>
    <authorgroup>
      <author>
	    <firstname>Ray</firstname>
	    <surname>Strode</surname>
        <affiliation>
            <address>
              <email>halfline hawaii rr com</email>
            </address>
        </affiliation>
      </author>
    </authorgroup>
  </articleinfo>

  <sect1 id="overview">
    <title>Overview</title>
    <para>
      The X Session Management Protocol (XSMP) specification
      introduces a protocol between a session manager and its
      clients.  The protocol gives the session manager control
      over when clients are started, stopped, and told to save
      and restore state.  While the basic protocol presented in
      the XSMP specification is useful, desktop environments
      require certain features not specified in the XSMP to be
      fully functional.
    </para>
    <para>
      This document serves to extend, clarify and when necessary
      override the XSMP for improved session management within
      desktop environments through the Desktop Session Management
      Extensions (DSME).  The document will primarily extend the 
      XSMP through the use of newly defined properties.  These
      properties should be treated similarly to the properties
      that are defined in section 11 of the XSMP.  Namely, each
      property, regardless of type, should be packed into a
      LISTofARRAY8 when sent to the session manager.  Also,
      unless explicitly stated otherwise, all properties should
      be first set after the client sends a
      <command>RegisterClient</command> message but before the
      client sends a <command>SaveYourselfDone</command> message.
    </para>
  </sect1>

  <sect1 id="definitions">
    <title>Definitions</title>
    <variablelist>
      <varlistentry>
	    <term>Active Session</term>
        <listitem>
          <para>
            An <firstterm>active session</firstterm> is the
            collection of application instances currently loaded
            and available to the user.  
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Application-specific State</term>
        <listitem>
          <para>
            One type of state associated with an application
            instance is <firstterm>application-specific
            state</firstterm>, which is information about the
            number of currently opened windows, what documents
            are open, and other information that is important for
            presenting to the user a consistent interface across
            login sessions.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Client</term>
        <listitem>
          <para>
            In the context of application-session manager
            interaction, a <firstterm>client</firstterm> is a
            session-managed application.  It connects to the
            session manager, identifies itself, and listens for
            commands (See the XSMP).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Desktop Environment</term>
        <listitem>
          <para>
            For this document a <firstterm>desktop
            environment</firstterm> is a collection of integrated
            applications and libraries written to provide an
            intuitive interface to the computer for users.
            Commonly, desktop environments have panels,
            desktop icons, and window managers.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Desktop Session Manager</term>
        <listitem>
          <para>
            A <firstterm>desktop session manager</firstterm> is a
            session manager (as defined by the XSMP) that is
            designed for managing clients in a desktop
            environment.  Desktop session managers are usually
            written specifically for a particular desktop
            environment and interact with users using facilities
            provided by that desktop environment.  It plays a 
            very important role for a desktop environment.  
            Namely, it serves to start all applications when the 
            user first logs in, to instruct all applications 
            to save their associated state, and also to terminate
            the active session when the user is ready to log out.

          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Document-specific State</term>
        <listitem>
          <para>
            One type of state associated with an application
            instance is <firstterm>document-specific
            state</firstterm>, which is the currently open
            documents.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Session</term>
        <listitem>
          <para>
            A <firstterm>session</firstterm> is a collection of
            saved instances of applications.  Each application
            instance has saved state that is specific to the
            session.  The session manager controls which session
            is loaded and made active on login by some
            implementation specific means.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>
  
  <sect1 id="identification">
    <title>Client Identification</title>
    <para>
      The XSMP provides mechanisms for clients to identify
      themselves to the session manager, but the mechanisms
      provided only give low-level representations of the
      clients.  There is no appropriate means of displaying the
      client to the user.  This section seeks to provide a means
      from which a desktop session manager can represent clients
      to the user through both localized client names and
      graphical icons.
    </para>
    <para>
      Some desktop environments have certain programs which
      provide integral functionality for the environment&apos;s
      proper operation. These programs need to be treated
      specially.  This section also seeks to provide a means for
      clients to identify themselves as special.
    </para>
    <sect2 id="client_name">
      <title>Localized Client Names</title>
      <para>
        Clients that support the DSME should set the
        <varname>_DSME_Name</varname> property to a preferred
        human-readable, localized application name encoded in
        UTF-8.  <varname>_DSME_Name</varname> is an ARRAY8
        property.
      </para>
    </sect2>
    <sect2 id="client_icon">
      <title>Client Icon</title>
      <para>
        Clients that support the DSME should set the
        <varname>_DSME_Icon</varname> property to a preferred icon
        name, which should be looked up by the desktop session
        manager using the procedure described in the Icon Theme
        Specification.  <varname>_DSME_Icon</varname> is an ARRAY8
        property.
      </para>
    </sect2>
    <sect2 id="client_role">
      <title>Client Role</title>
      <para>
        Clients that support the DSME may set the
        <varname>_DSME_Roles</varname> property to reflect their
        roles in the desktop environment.  If a client chooses
        not to set the <varname>_DSME_Roles</varname> property the
        desktop session manager should assume the client has an
        implicit role of <literal>_DSME_RoleNormal</literal>.
        <varname>_DSME_Roles</varname> is a CARD8 property.  A
        client can specify more than one role by performing a
        bitwise <command>OR</command> operation on the possible
        role values:
        <itemizedlist>
            <listitem>
                <para>
                    <literal>_DSME_RoleNormal</literal>
                    (<literal>0x0</literal>).  All clients that
                    do not set any other role may set this role.
                    A client with only this role set should not
                    be treated specially by the session manager.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleWindowManager</literal>
                    (<literal>0x1</literal>).  Window managers
                    must set this role.  Desktop session managers
                    must only allow one client per session with
                    this role set.  In the event that more than
                    one client sets this role during login then
                    the client with lowest priority should be
                    loaded.  If a client attempts to register
                    with the session manager in the middle of an
                    active session and another client is already
                    running with this role set, then the desktop
                    session manager should send a
                    <command>Die</command> message to the newer
                    client.  If a session manager detects that a
                    session is lacking a client with this role
                    set, then it may optionally start a suitable
                    client.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleDesktopHandler</literal>
                    (<literal>0x2</literal>). Programs that take
                    control of desktop handling (like some file
                    managers) must set this role. Desktop session
                    managers must only allow one client per
                    session with this role set.  In the event
                    that more than one client sets this role
                    during login then the client with lowest
                    priority should be loaded.  If a client
                    attempts to register with the session manager
                    in the middle of an active session and
                    another client is already running with this
                    role set, then the desktop session manager
                    should send a <command>Die</command> message
                    to the newer client.  If a session manager
                    detects that a session is lacking a client
                    with this role set, then it may optionally
                    start a suitable client.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RolePanel</literal>
                    (<literal>0x4</literal>).  Panels must set
                    this role.  If a session manager detects that
                    a session is lacking a client with this role
                    set, then it may optionally start a suitable
                    client.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleDesktopComponent</literal>
                    (<literal>0x8</literal>).  All resident
                    components of the desktop not specified by
                    other other role types in this document
                    should set this role.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleSetup</literal>
                    (<literal>0x10</literal>).  Programs that
                    load user preferences (like desktop
                    backgrounds, audio settings, etc) should set
                    this role.
                </para>
            </listitem>
        </itemizedlist>
      </para>
    </sect2>
  </sect1>
  <sect1 id="load_order">
    <title>Client Load Order</title>
    <para>
      The order in which clients are started on login is often
      important for a proper user experience.  For instance,
      under normal circumstances the window manager needs to be
      loaded before clients with managed windows in order to
      prevent the flickering of window decorations being added to
      already mapped windows.  Also, other intrinsic components
      of the desktop should normally be started before user
      applications.  This section seeks to provide a mechanism
      for controlling the order in which clients are loaded on
      login.  This section does not address situations where the
      user is already logged in and there is an active session
      loaded.
    </para>
    <sect2 id="client_priority">
      <title>Client Priority</title>
      <para>
        Clients that support the DSME may set the
        <varname>_DSME_Priority</varname> property to reflect when
        they would like to be launched on user login.
        <varname>_DSME_Priority</varname> is a CARD8 property.
        Clients that set this property to low values should be
        started before clients that set this property to higher
        values.  If a client chooses not to set this property,
        then the session manager should assume an implicit
        priority for the client based on the client&apos;s role:  
        </para>
        <informaltable>
            <tgroup cols="2">
              <thead>
                <row>
                  <entry>Client Role</entry> 
                  <entry>Implied Client Priority</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <literal>_DSME_RoleWindowManager</literal>
                  </entry>
                  <entry><literal>10</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleSetup</literal>
                  </entry>
                  <entry><literal>20</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleDesktopHandler</literal>
                  </entry>
                  <entry><literal>30</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RolePanel</literal>
                  </entry>
                  <entry><literal>40</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleDesktopComponent</literal>
                  </entry>
                  <entry><literal>40</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleNormal</literal>
                  </entry>
                  <entry><literal>50</literal></entry>
                </row>
              </tbody>
            </tgroup>
        </informaltable>
        <para>
          In the event that more than one client sets this
          property to the same value the order that these clients
          are loaded is undefined.  However, the desktop session
          manager may choose to look at each client&apos;s role
          in determining which client to load first.
        </para>
    </sect2>
  </sect1>
  <sect1 id="session_saving">
  <title>Session Saving and Logging Out</title>
  <para>
    Often individual application instances in desktop
    environments will have two distinct types of state.  The
    first type of state is application-specific state and the
    other is document-specific state.
  </para>
  <para>
    Application-specific state is information about the number of
    currently opened windows, what documents are open, and other
    information that is important for presenting to the user a
    consistent interface across login sessions.  This type of
    information is important for a seamless user experience, but
    it is not the type of information that users should be able
    to collectively save or discard on a per-application basis.
  </para>
  <para>
    When a user is done using the computer, if that user chooses
    to save the active session, then the application-specific
    state of all currently running application instances should
    be transparently saved for the user.  On the other hand, if
    the user chooses not to save the current session on log out,
    then the application-specific state of all currently running
    application instances should be discarded and when the user
    logs in again the most recently saved session and all its
    associated application-specific state should be loaded.
  </para>  
  <para>
    While application-specific state should be handled
    transparently for the user, document-specific state may
    involve the user.  Document-specific state is the actual open
    documents themselves.  It is much more tangible to the user
    than application-specific state because many users are
    accustomed to directly controlling what goes into their
    documents.  This control includes, for instance, what gets
    typed into the documents, but more importantly for this
    section, when the documents are saved.
  </para>
  <para>
    When the user is done using the computer and attempts to log
    out, all open and unsaved documents may be optionally saved
    or discarded on a per-document basis based on individual
    decisions from the user.  This process may happen regardless
    of whether the user chose to save the active session or not.
  </para>
  <sect2 id="saveyourself_semantics">
    <title>
      <command>SaveYourself</command> Message Semantics
    </title>
    <para>
      When desktop session managers send the
      <command>SaveYourself</command> message to clients the
      <literal>Local</literal> save type indicates that clients
      must save their application-specific state.  The
      <literal>Global</literal> save type indicates that clients
      must save their document-specific state.  In the event that
      save type is <literal>Both</literal> the clients should
      first save document-specific state and then save
      application-specific state.  
    </para>
    <para>
      When the user logs out, the session manager must send a
      <command>SaveYourself</command> message to all clients. If
      the user chose to save the active session when initiating
      the logout request, then the save type should be
      <literal>Both</literal>.  Otherwise, the save type should
      be <literal>Global</literal>.
    </para>
     <para>
      While a DSME-compliant client must only save
      application-specific state if it receives a
      <command>SaveYourself</command> message with the
      <literal>Local</literal> or <literal>Both</literal> save
      type, it is possible that non DSME-compliant clients will
      save application-specific state for the
      <literal>Global</literal> save type.  For this reason, the
      session manager should run the
      <command>DiscardCommand</command> commands of all relevent
      clients following any <command>SaveYourself</command>
      message with save type <literal>Global</literal>.  If the
      <command>SaveYourself</command> message was the result of a
      <command>SaveYourselfRequest</command> message with 
      <varname>global</varname> set to <literal>False</literal> 
      then the only relevent client is the client that initiated 
      the <command>SaveYourselfRequest</command> message.  In all
      other cases, the <command>DiscardCommand</command> command
      of every client should be run.
    </para>
    <sect3 id="session_shutdown">
      <title>Session Shutdown</title> 
      <para>
        A client that wishes to terminate the active session
        should set the <varname>_DSME_ShutdownMode</varname>
        property with the value of the requested method of
        session termination and then immediately send a
        <command>SaveYourselfRequest</command> with 
        <varname>shutdown</varname> set to 
        <literal>True</literal>.
        <varname>_DSME_ShutdownMode</varname> is a CARD8 property,
        which can be set to one of several possible values:
        <itemizedlist>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownDefault</literal>
                    (<literal>0x0</literal>).  The session
                    manager should terminate the active session
                    in an implementation-dependent manner.  The
                    session manager may choose to terminate the
                    active session using a user-configurable
                    setting or by remembering the previously used
                    shutdown mode.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownModeLogOut</literal>
                    (<literal>0x1</literal>).  The session
                    manager should log out of the active session.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownModeReboot</literal>
                    (<literal>0x2</literal>).  The session
                    manager should reboot the computer.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownModeHalt</literal>
                    (<literal>0x4</literal>).  The session
                    manager should halt the computer.
                </para>
            </listitem>
        </itemizedlist>
        When the session manager receives a
        <command>SaveYourselfRequest</command> with 
        <varname>shutdown</varname> set to 
        <literal>True</literal> it should terminate the session 
        in the manner specified by initiating client&apos;s
        <varname>_DSME_ShutdownMode</varname> property provided 
        that the session manager supports the shutdown mode.  If 
        the initiating client did not set the
        <varname>_DSME_ShutdownMode</varname> property, then the
        session manager should assume an implied shutdown mode of
        <literal>_DSME_ShutdownModeLogOut</literal> for
        compatibility.  If the client set the shutdown mode to
        an unsupported value then the session manager should
        cancel the shutdown request.
      </para>
      <para>
        The session manager should inform its clients what 
        shutdown modes it supports with
        <varname>_DSME_AvailableShutdownModes</varname>,
        which is a CARD8 property whose value is the bitwise
        <command>OR</command> of all supported shutdown modes. 
        The session manager should set this property on every
        new client before sending the client a 
        <command>RegisterClientReply</command> message.  The
        session manager must not change this property after 
        initially setting it. Clients should assume an implied
        value of <literal>_DSME_ShutdownModeLogOut</literal> if
        the session manager fails to set 
        <varname>_DSME_AvailableShutdownModes</varname> for 
        compatibility.   
      </para>
      <para>
        Before a client initiates a 
        <command>SaveYourselfRequest</command> with 
        <varname>shutdown</varname> set to
        <literal>True</literal> it should specify whether or not
        the user should participate in the shutdown process, by 
        setting the <varname>_DSME_ShutdownInteractMode</varname> 
        property.  <varname>_DSME_ShutdownInteractMode</varname> 
        is a CARD8 property with several possible values:
        <itemizedlist>
          <listitem>
            <para>
              <literal>_DSME_ShutdownInteractModeDefault</literal>
              (<literal>0</literal>).  The session manager should
              instruct clients whether or not to interact with 
              the user based on an implementation-dependent
              method.  The session manager may choose to follow 
              a user-configurable setting or choose to treat this
              option like 
              <literal>_DSME_ShutdownInteractModeActive</literal>.
            </para>
          </listitem>
          <listitem>
            <para>
              <literal>_DSME_ShutdownInteractModeActive</literal>
              (<literal>1</literal>).  The session manager 
              should instruct clients to query the user for 
              confirmation before saving document-specific state.  
              Specifically, session managers should set 
              <varname>interact-style</varname> to 
              <literal>Any</literal> and <varname>fast</varname>
              to <literal>False</literal> when sending each 
              client a <command>SaveYourself</command> message.
            </para>
          </listitem>
          <listitem>
            <para>
              <literal>_DSME_ShutdownInteractModePassive</literal>
              (<literal>2</literal>).  The session manager 
              should instruct clients to automatically save 
              document-specific state without interacting with
              the user.  Specifically, session managers should 
              set <varname>interact-style</varname> to 
              <literal>None</literal> and <varname>fast</varname>
              to <literal>True</literal> when sending each client
              a <command>SaveYourself</command> message.
            </para>
          </listitem>
        </itemizedlist>    
      </para>
      <para>
        If a client initiates a 
        <command>SaveYourselfRequest</command> with 
        <varname>shutdown</varname> set to 
        <literal>True</literal> but does not set the 
        <varname>_DSME_ShutdownInteractMode</varname> property 
        first, then the session manager should assume an implied 
        mode of 
        <literal>_DSME_ShutdownInteractModeActive</literal> if the
        client initiating the request set <varname>fast</varname>
        to <literal>False</literal> and the session manager 
        should assume an implied mode of 
        <literal>_DSME_ShutdownInteractModePassive</literal> if 
        the client initiating the request set 
        <varname>fast</varname> to <literal>True</literal>.  
        Note the session manager should ignore the 
        <varname>fast</varname> argument of the initiating 
        client&apos;s <command>SaveYourselfRequest</command>
        message if the 
        <varname>_DSME_ShutdownInteractMode</varname>
        property is set.  Also, the session manager should always
        ignore the <varname>interact-style</varname> argument of
        the message.

      </para>
    </sect3>
  </sect2>
  </sect1>
  <appendix id="changes">
    <title>Change History</title>
    <formalpara>
      <title>Version 0.6, 31 December 2003, Ray Strode</title>    
      <para>
        <itemizedlist>
          <listitem>
            <para>
              Added <varname>_DSME_ShutdownMode</varname> from
              suggestion by Mark Finlay.
            </para>
          </listitem>
          <listitem>
            <para>
              Alluded to section 11 of the XSMP for clarification 
              of the nature of the properties from suggestion by 
              Olivier Chapuis.
            </para>
          </listitem>
          <listitem>
            <para>
              Added <literal>_DSME_ShutdownModeDefault</literal>
              and added &quot;for compatibility&quot; to 
              explanation of implicit shutdown mode from 
              suggestion by Oswald Buddenhagen.
            </para>
          </listitem>
          <listitem>
            <para>
              Added <varname>_DSME_ShutdownInteractMode</varname>
              property from suggestion by Oswald Buddenhagen.
            </para>
          </listitem>
          <listitem>
            <para>
              Changed quotations and apostrophes to entities.
              Added more semantic markup.
            </para>
          </listitem>
          <listitem>
            <para>
              Changed <literal>_DSME_Role_DesktopManager</literal>
              to <literal>_DSME_Role_DesktopHandler</literal> to
              prevent confusion from desktop managers like xdm,
              kdm, and gdm.
            </para>
          </listitem>
          <listitem>
            <para>
              Added
              <varname>_DSME_AvailableShutdownModes</varname> so
              clients can query the session manager for available
              shutdown modes.
            </para>
          </listitem>
          <listitem>
            <para>
              Changed prefix to _DSME_ instead of _NET_ to 
              prevent confusion with EWMH spec by suggestion from
              Olivier Chapuis.
            </para>
          </listitem>
          <listitem>
            <para>
              Fixed Typos.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.5, 28 December 2003, Ray Strode</title>    
      <para>
      Initial Draft.
      </para>
    </formalpara>
  </appendix>
</article>


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]