Desktop/Whiteboards/InhibitApis

Problem

The Inhibit pattern has proven to be quite successful. It is a good way for applications to proactively inform the system about actions that should not be taken.

Firstly, we offer too many ways to do this. We currently (as of GNOME 2.24) have the following:

• http://www.gnome.org/~mccann/gnome-screensaver/docs/gnome-screensaver.html#gs-method-Inhibit
• http://people.freedesktop.org/~hughsient/temp/dbus-interface.html#dbus-inhibit
• http://www.gnome.org/~mccann/gnome-session/docs/gnome-session.html#org.gnome.SessionManager.Inhibit

Secondly, it is not always possible to know ahead of time if an action should be avoided. So, there is often a need for the QueryEndSession pattern. This pattern has been partially implemented in gnome-session 2.24. See http://live.gnome.org/SessionManagement/GnomeSession .

Use Cases

Watching a movie on laptop screen

• Movie player should inhibit idleness

Close laptop lid:

• Suspend

Select suspend menu:

• Suspend

Lock screen / Set 'away':

• Stop playing movie
• Lock screen

Watching a movie with laptop plugged into an external monitor/TV

• Movie player should inhibit idleness

Close laptop lid:

• Turn off laptop panel backlight
• Do not suspend until after next idle period after movie finishes playing

Select suspend menu:

• Suspend

Lock screen / Set 'away':

• Stop playing movie
• Lock screen

Listening to music on laptop while in another room

• Not sure about this one
• Inhibiting idleness would not be good because we want to power down the screen
• Probably inhibiting suspend is the right choice

Close laptop lid:

• Suspend

Select suspend menu:

• Suspend

Lock screen / Set 'away':

• Continue playing music
• Lock screen

NOTE: different Lock screen behavior from Playing movie.

NOTE: Probably wouldn't expect Suspend menu to ask for confirmation as it would in the logout inhibited case or the suspend while burning CD case.

Burning a CD

• Perfectly fine to be idle and lock the screen if necessary
• Inhibit suspend
• Inhibit user switch (once we have frevoke)
• Inhibit logout
• Not necessary to inhibit reboot or shutdown since logout and switch are inhibited

Transferring files to a removable disk

• Same as Burning a CD

Performing a core system software update

• Only inhibit system reboot/shutdown?

Performing an application software update

• Only inhibit system reboot/shutdown?
• Maybe even fail and try again

Editing a document

• Only inhibit logout

Playing a game

• Inhibit idleness

Discussion

Overview of actions

Action	Interface
Session idleness	org.gnome.ScreenSaver.Inhibit
Automatic screen locking	org.gnome.ScreenSaver.Inhibit
Switching users	org.gnome.SessionManager.Inhibit
Automatic suspend	org.freedesktop.PowerManagement.Inhibit
Automatic hibernation	org.freedesktop.PowerManagement.Inhibit
Logout	org.gnome.SessionManager.Inhibit
Reboot/Shutdown	TBD

It should be stressed that Inhibiting is not the same as blocking. The same was chosen to express a difference. An Inhibit should:

• prevent automatic/non-interactive actions

Example: prevent automatic suspend after a period of idleness

• inform manual/interactive actions

Example: Inform the user about the risk of dataloss when selecting power off from the menu

• not interfere with manual/non-interactive actions

Example: Closing the lid when there is no way to interact with the user should not block suspend

How do we differentiate the cases where a manual/interactive action should ask for confirmation and those where it should not? For example, selecting suspend while playing music should not ask for confirmation but selecting suspend while burning a CD probably should. Maybe the difference is that one is "I'm doing something" and the other is "I'm doing something that will break". I think this is why Richard changed the GNOME Power Manager Inhibit API to be InhibitAuto and InhibitManual at one point. Would something like a confirm-override=true flag suffice for the second case?

Is there a need for any inhibiting at the system level? For most of the cases, it seems like the answer is no. We should also be careful about not exposing leaking information from on session to another. We should also be aware that the translated reason strings will not be relevent outside the session they originate from.

On the other hand, in the cases where the QES pattern is needed we may need system level support. Unless we say that once a session has become inactive then all bets are off. But what about multi-seat systems where there can be multiple active sessions?

What about cases where you want to offload running jobs before shutting down? That would probably have to be a privileged operation. For system level daemons that is not a problem. But how do we define a trust relationship with untrusted user sessions? Possibly the only process in a user session that can be trusted at all is the parent process (eg. gnome-session). But even then it isn't trustworthy if it can dynamically load any code. So, perhaps the best we can do is to have an a way for the session to grab control of a root level service on a first come first served basis. Something similar to D-Bus bus names perhaps.

Perhaps we could use something similar to the QES API design in gnome-session.

How might this work. Here's one way:

1. PID1 calls org.gnome.ConsoleKit.System.Stop
2. ConsoleKit checks that PID1 is authorized to perform action
3. If not authorized, ConsoleKit returns error immediately
4. Otherwise, ConsoleKit asks all registered Sessions if action may be performed
5. If Session has a Referent connected, unicast signal it to see if action may be performed
6. If Referent session has already Inhibited the action it should return that result immediately
7. Otherwise, Referent session should unicast signal all connected clients to see if the action may be performed. See ClientPrivate interface

Active sessions should probably get more time to respond than inactive ones. Even still this would only be acceptable if the response time didn't interfere with the user's experience.

References

• http://bugzilla.gnome.org/show_bug.cgi?id=334809#c6