RFC: idle protocol

[Pekka Paalanen]

On Tue, 08 Dec 2015 14:12:01 +0100
Martin Graesslin <mgraesslin at kde.org> wrote:

> Hi Wayland-developers,
> 
> at KDE we developed a protocol for our framework kidletime [1]. The idea is to 
> notify Wayland clients when a wl_seat has been idle for a specified time. We 
> use this for example for power management, screen locking etc. But a common 
> use case is also setting a user as away in a chat application.
> 
> We think that this protocol can be in general useful for all Wayland based 
> systems. Our current protocol is attached to this mail. Of course for 
> integration into wayland protocols the namespace needs adjustments (I'm open 
> for suggestions).
> 
> The reference implementation of the protocol can be found in the KWayland 
> repository (client at [2], server at [3]).
> 
> Best Regards
> Martin Gräßlin
> 
> [1] http://inqlude.org/libraries/kidletime.html
> [2] git://anongit.kde.org/kwayland (path src/client/idle.h and src/client/
> idle.cpp)
> [3] git://anongit.kde.org/kwayland (path src/server/idle_interface.h and src/
> server/idle_interface.cpp)

Hi Martin,

nice to hear from you. :-)

I'll comment just on the destructor protocol below.

> <?xml version="1.0" encoding="UTF-8"?>
> <protocol name="idle">
>   <copyright><![CDATA[
>     Copyright (C) 2015 Martin Gräßlin
> 
>     This program is free software: you can redistribute it and/or modify
>     it under the terms of the GNU Lesser General Public License as published by
>     the Free Software Foundation, either version 2.1 of the License, or
>     (at your option) any later version.
> 
>     This program is distributed in the hope that it will be useful,
>     but WITHOUT ANY WARRANTY; without even the implied warranty of
>     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>     GNU Lesser General Public License for more details.
> 
>     You should have received a copy of the GNU Lesser General Public License
>     along with this program.  If not, see <http://www.gnu.org/licenses/>.
>   ]]></copyright>  
>   <interface  name="org_kde_kwin_idle" version="1">
>       <description summary="User idle time manager">
>         This interface allows to monitor user idle time on a given seat. The interface
>         allows to register timers which trigger after no user activity was registered
>         on the seat for a given interval. It notifies when user activity resumes.
> 
>         This is useful for applications wanting to perform actions when the user is not
>         interacting with the system, e.g. chat applications setting the user as away, power
>         management features to dim screen, etc..

This looks like an interface advertised as a global via wl_registry.
One can often pick it up implicitly from the doc, but being explicit
would be nice.

>       </description>
>       <request name="get_idle_timeout">
>         <arg name="id" type="new_id" interface="org_kde_kwin_idle_timeout"/>
>         <arg name="seat" type="object" interface="wl_seat"/>
>         <arg name="timeout" type="uint" description="The idle timeout in msec"/>
>       </request>

Missing destructor protocol. We've made this mistake in Wayland core in
lots of places. Without a destructor, the server can never know when
the client is done using this protocol object (created with
wl_registry.bind). Unless of course the client disconnects - in the
early days we thought disconnect is enough to handle things, and
sometimes it is, but adding a destructor message is cheap, safe, and
obvious.

>   </interface>
>   <interface name="org_kde_kwin_idle_timeout" version="1">
>       <request name="release" type="destructor">

We use the name "release" in Wayland core when the first stable release
of the interface didn't include destructor protocol, but such was found
necessary later. This should be called "destroy" if possible, so it
coincides with the *_destroy() function automatically generated by
wayland-scanner.

>         <description summary="release the timeout object"/>
>       </request>
>       <request name="simulate_user_activity">
>           <description summary="Simulates user activity for this timeout, behaves just like real user activity on the seat"/>
>       </request>
>       <event name="idle">
>           <description summary="Triggered when there has not been any user activity in the requested idle time interval"/>
>       </event>
>       <event name="resumed">
>           <description summary="Triggered on the first user activity after an idle event"/>
>       </event>
>   </interface>
> </protocol>

If you want to read more about destruction, I have written
http://ppaalanen.blogspot.fi/2014/07/wayland-protocol-design-object-lifespan.html


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20151221/1b3a7817/attachment.sig>