[PATCH] unstable: add xdg-session-management protocol
Markus Ongyerth
wl at ongy.net
Tue Feb 27 17:14:46 UTC 2018
On 2018/2月/26 08:58, Mike Blumenkrantz wrote:
> for a variety of cases it's desirable to have a method for negotiating
> the restoration of previously-used states for a client's windows. this
> helps for e.g., a compositor/client crashing (definitely not due to
> bugs) or a backgrounded client deciding to temporarily destroy its
> surfaces in order to conserve resources
What's the intended workflow for the background client?
The protocol states that the session data should be removed on
xdg_toplevel.destroy, which would not allow clients to reuse state after they
gracefully exited, or "exited" partially (closing some windows, not the entire
connection).
>
> this protocol adds a method for managing such negotiation and is loosely
> based on the Enlightenment "session recovery" protocol which has been
> implemented and functional for roughly two years
>
> some further reading: https://blogs.s-osg.org/recovery-journey-discovery/
>
> Signed-off-by: Mike Blumenkrantz <zmike at osg.samsung.com>
> Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> ---
> Makefile.am | 1 +
> unstable/xdg-session-management/README | 4 +
> .../xdg-session-management-unstable-v1.xml | 181 +++++++++++++++++++++
> 3 files changed, 186 insertions(+)
> create mode 100644 unstable/xdg-session-management/README
> create mode 100644 unstable/xdg-session-management/xdg-session-management-unstable-v1.xml
>
> diff --git a/Makefile.am b/Makefile.am
> index 4b9a901..2b75114 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -17,6 +17,7 @@ unstable_protocols = \
> unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml \
> unstable/xdg-output/xdg-output-unstable-v1.xml \
> unstable/input-timestamps/input-timestamps-unstable-v1.xml \
> + unstable/xdg-session-management/xdg-session-management-unstable-v1.xml \
> $(NULL)
>
> stable_protocols = \
> diff --git a/unstable/xdg-session-management/README b/unstable/xdg-session-management/README
> new file mode 100644
> index 0000000..7bff401
> --- /dev/null
> +++ b/unstable/xdg-session-management/README
> @@ -0,0 +1,4 @@
> +xdg session management protocol
> +
> +Maintainers:
> +Mike Blumenkrantz <zmike at osg.samsung.com>
> diff --git a/unstable/xdg-session-management/xdg-session-management-unstable-v1.xml b/unstable/xdg-session-management/xdg-session-management-unstable-v1.xml
> new file mode 100644
> index 0000000..0c36c16
> --- /dev/null
> +++ b/unstable/xdg-session-management/xdg-session-management-unstable-v1.xml
> @@ -0,0 +1,181 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="session management">
> + <copyright>
> + Copyright 2018 Mike Blumenkrantz
> + Copyright 2018 Samsung Electronics Co., Ltd
> + Copyright 2018 Red Hat Inc.
> +
> + Permission is hereby granted, free of charge, to any person obtaining a
> + copy of this software and associated documentation files (the "Software"),
> + to deal in the Software without restriction, including without limitation
> + the rights to use, copy, modify, merge, publish, distribute, sublicense,
> + and/or sell copies of the Software, and to permit persons to whom the
> + Software is furnished to do so, subject to the following conditions:
> +
> + The above copyright notice and this permission notice (including the next
> + paragraph) shall be included in all copies or substantial portions of the
> + Software.
> +
> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
> + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> + DEALINGS IN THE SOFTWARE.
> + </copyright>
> + <description summary="Protocol for managing application sessions">
> + Warning! The protocol described in this file is experimental and backward
> + incompatible changes may be made. Backward compatible changes may be added
> + together with the corresponding interface version bump. Backward
> + incompatible changes are done by bumping the version number in the protocol
> + and interface names and resetting the interface version. Once the protocol
> + is to be declared stable, the 'z' prefix and the version number in the
> + protocol and interface names are removed and the interface version number is
> + reset.
> + </description>
> + <interface name="zxdg_session_manager_v1" version="1">
> + <description summary="manage sessions for applications">
> + The xdg_session_manager interface defines base requests for creating and
> + managing a session for an application. Sessions persist across application
> + and compositor restarts unless explicitly destroyed. A session is created
> + for the purpose of maintaining an application's xdg_toplevel surfaces
> + across compositor or application restarts. The compositor should remember
> + as many states as possible for surfaces in a given session, but there is
> + no requirement for which states must be remembered.
> + </description>
> + <request name="destroy" type="destructor">
> + <description summary="Destroy this object">
> + This has no effect other than to destroy the xdg_session_manager object.
> + </description>
> + </request>
> + <request name="get_session">
> + <description summary="create or restore a session">
> + Create a session object corresponding to the given session
> + identifier string. While the session object exists, the session is
> + considered to be "in use".
> +
> + It is a client error if the given identifier string represents a session
> + which is already in use.
> +
> + NULL is passed to initiate a new session. If an id is passed which does
> + not represent a valid session, the compositor treats it as if NULL had
> + been passed.
> + </description>
> + <arg name="id" type="new_id" interface="zxdg_session_v1"/>
> + <arg name="session" type="string" summary="the session identifier string"
> + allow-null="true"/>
> + </request>
> + </interface>
> + <interface name="zxdg_session_v1" version="1">
> + <description summary="A session for an application">
> + A xdg_session object represents a session for an application. While the
> + object exists, all surfaces which have been added to the session will
> + have states stored by the compositor which can be reapplied at a later
> + time. Two sessions cannot exist for the same identifier string.
> +
> + States for surfaces added to a session are automatically updated by the
> + compositor when they are changed.
> +
> + Surfaces which have been added to a session are automatically removed from
> + the session if xdg_toplevel.destroy is called for the surface.
> + </description>
> + <enum name="error">
> + <entry name="in_use" summary="a requested session is already in use"
> + value="1"/>
> + <entry name="invalid_restore"
> + summary="restore cannot be performed after initial toplevel commit"
> + value="2"/>
> + </enum>
> + <request name="destroy" type="destructor">
> + <description summary="Destroy the session">
> + Destroy a session object, preserving the current state but not continuing
> + to make further updates if state changes occur.
> + </description>
> + </request>
> + <request name="remove" type="destructor">
> + <description summary="Remove the session">
> + Remove a session from the compositor's storage, destroying
> + all xdg_session objects and all session data recursively.
> + </description>
> + </request>
> + <request name="add_surface">
> + <description summary="add a new surface to the session">
> + Attempt to add a given surface to the session. If successful,
> + a zxdg_surface_session_v1.surface_id event is emitted with a
> + session-unique identifier which can be used to restore states of the
> + toplevel surface.
> +
> + Multiple requests for the same surface will always return the same
> + string identifier.
> +
> + The surface will be added to the session at the next wl_surface.commit.
> + </description>
> + <arg name="surface" type="object" interface="xdg_toplevel"/>
> + <arg name="id" type="new_id" interface="zxdg_surface_session_v1"/>
> + </request>
> + <request name="restore_surface">
> + <description summary="restore a surface state">
> + Inform the compositor that the next configured state should
> + be the same as the state which was stored by the compositor during the
> + given surface's previous session.
> +
> + This request must be called prior to the first commit for an
> + xdg_toplevel surface.
> +
> + See the zxdg_surface_session_v1.surface_restored event for further
> + details.
> + </description>
> + <arg name="id" type="new_id" interface="zxdg_surface_session_v1"/>
> + <arg name="surface" type="object" interface="xdg_toplevel"/>
> + <arg name="surface_id" type="string"
> + summary="the identifier for the surface"/>
> + </request>
> + <request name="remove_surface">
> + <description summary="remove a surface from the session">
> + Remove a specified surface from the session and render any corresponding
> + xdg_surface_session object inert.
> +
> + Passing an unknown surface identifier has no effect.
> + </description>
> + <arg name="surface_id" type="string"/>
> + </request>
> + <event name="created">
> + <description summary="newly-created session id">
> + Emitted immediately after creating a new session object. This id can be
> + used to restore previous sessions.
> + </description>
> + <arg name="id" type="string"/>
> + </event>
> + <event name="restored">
> + <description
> + summary="the session has been restored from a previous state"/>
> + </event>
> + </interface>
> + <interface name="zxdg_surface_session_v1" version="1">
> + <request name="destroy" type="destructor">
> + <description summary="Destroy the object">
> + Destroy the object.
> + </description>
> + </request>
> + <event name="surface_restored">
> + <description summary="a surface's session has been restored">
> + surface_restored is emitted prior to the first xdg_surface.configure for
> + a surface. It will only be emitted after zxdg_session_v1.restore_surface
> + and wl_surface.commit have been called for that surface, and it
> + indicates that the surface's session is being restored with this
> + configure event.
> + </description>
> + <arg name="surface" type="object" interface="xdg_toplevel"/>
> + </event>
> + <event name="surface_id">
> + <description summary="a surface has been added to the session">
> + surface_id is emitted after the wl_surface.commit of a surface which has
> + been passed to add_surface. The id is an identifier which can be passed
> + to restore_surface to restore the state of that surface.
> + </description>
> + <arg name="surface" type="object" interface="xdg_toplevel"/>
> + <arg name="id" type="string"/>
Is there a reason to make this a string? Looking at this it looks like it
could be a counter serverside and maybe uint32 in the protocol?
Unless of course a session is intended to live for longer than 2^32 objects
that can't be recycled.
From a first glance, the compositor does not have to add any disambiguation
information here, since it's session local (and sessions have unique id
strings), does not have any good idea to name it (using app-id or title
wouldn't be very robust), and can't encode anything into it.
> + </event>
> + </interface>
> +</protocol>
> --
> 2.14.3
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20180227/612d8fbb/attachment-0001.sig>
More information about the wayland-devel
mailing list