Wakepy Methods

Wakepy Methods#

What are wakepy Methods? Methods are different ways of entering in (or keeping a) Mode. A Method may support one or more platforms, and may have one or more requirements for software it should be able to talk to or execute. For example, on Linux, using the Inhibit method of the org.gnome.SessionManager D-Bus service is one way of entering the keep.running mode, and it requires D-Bus and (a certain version of) GNOME. The following methods exist (⌛: keep.running, 🖥️: keep.presenting):

Method

Modes

caffeinate

⌛ 🖥️

org.freedesktop.PowerManagement

⌛

org.freedesktop.ScreenSaver

🖥️

org.gnome.SessionManager

⌛🖥️

SetThreadExecutionState

⌛🖥️

caffeinate#

  • Name: caffeinate

  • Modes: keep.running, keep.presenting

  • Introduced in: wakepy 0.3.0

  • How it works: It calls the caffeinate command to activate the keep.running mode and add the -d flag (“Create an assertion to prevent the display from sleeping.”) for keep.presenting mode. See docs at ss64.com or at archives from developer.apple.com

  • Multiprocess safe?: Yes

  • What if the process holding the lock dies?: The lock is automatically removed.

  • How to check it?: You should be able to see a process with a command /bin/bash caffeinate or similar associated with it using a task manager.

  • Requirements: Mac OS X 10.8 Mountain Lion (July 2012) or newer. Ref: Interesting new UNIX commands/binaries in OS X Mountain Lion, (2012-07-27 by Patrick Seemann, link), Disable Sleep on a Mac from the Command Line with caffeinate (2012-08-03, OSX Daily, link).

org.freedesktop.PowerManagement#

  • Name: org.freedesktop.PowerManagement

  • Modes: keep.running

  • Introduced in: wakepy 0.9.0

  • How it works: Uses the Inhibit method of the org.freedesktop.PowerManagement D-Bus service when activating and saves the returned cookie on the Method instance. Uses UnInhibit method of the same service with the cookie when deactivating. The org.freedesktop.PowerManagement is an obsolete spec, but certain Desktop Environments provide that as the only option for inhibiting the suspend action. The documentation was previously hosted on freedesktop.org but the links on the page are dead. The spec has three versions: 0.1, 0.2 and 0.3. The 0.3 is not found anywhere but the version 0.2 of the spec can be read in the Internet Archive

  • Multiprocess safe?: Yes

  • What if the process holding the lock dies?: The lock is automatically removed.

  • How to check it?: You may check if there are any inhibitors using the HasInhibit method of the /org/freedesktop/PowerManagement/Inhibit object on the org.freedesktop.PowerManagement.Inhibit interface. Note that updating the inhibit flag from false to true may take a few seconds. A good tool for this is D-Spy. Alternatively, you could monitor your inhibit call with dbus-monitor.

  • Requirements: D-Bus + KDE Plasma >=5.12.90 or other DE which implements this older freedesktop D-Bus interface. Exception: Xfce is not supported.

  • About unsupported DEs Older versions of KDE Plasma had a bug which also prevented the screenlock/screesaver activation. The bug was fixed in D11182, commit 152400c1b688 and was part of the KDE Plasma 5.12.90 ( = 5.13 Beta) release. This Method is not supported either on Xfce as it has similar bug which prevents also the automatic screenlock/screensaver (See: xfce4-power-manager/#65), hence, wakepy refuses to use org.freedesktop.PowerManagement as method for keep.running mode on KDE < 5.12.90 and on any version of Xfce.

  • Post Keepawake Behavior: Resetting type on KDE (KDE Plasma 5.27.11, tested by reidswanson on #366).

  • Tested on: openSUSE 15.5 with KDE Plasma 5.27.9 (Comment in #310 by fohrloop).

org.freedesktop.ScreenSaver#

  • Name: org.freedesktop.ScreenSaver

  • Modes: keep.presenting

  • Introduced in: wakepy 0.6.0

  • How it works: Uses the Inhibit method of org.freedesktop.ScreenSaver D-Bus service when activating and saves the returned cookie on the Method instance. Uses the org.freedesktop.ScreenSaver.UnInhibit method with the cookie when deactivating. The org.freedesktop.ScreenSaver can only be used to prevent idle; that is why there is no “keep.running” mode counterpart.

  • Multiprocess safe?: Yes

  • What if the process holding the lock dies?: The lock is automatically removed.

  • How to check it?: The org.freedesktop.ScreenSaver does not expose a method for listing the inhibitors, but you could monitor your inhibit call with dbus-monitor.

  • Requirements: D-Bus, and a freedesktop.org compliant desktop environment, which should implement the org.freedesktop.ScreenSaver.Inhibit method.

  • Post Keepawake Behavior: Resetting type on GNOME 47 (#471). The behavior is likely to depend on the used DE.

  • Tested on: Ubuntu 22.04 with GNOME 42.9 (wakepy/#171) and openSUSE 15.5 with KDE Plasma 5.27.9 (wakepy/#310) by fohrloop.

org.gnome.SessionManager#

  • Name: org.gnome.SessionManager

  • Modes: keep.running, keep.presenting

  • Introduced in: wakepy 0.8.0

  • How it works: Uses the Inhibit method of org.gnome.SessionManager D-Bus service when activating and saves the returned cookie on the Method instance. For keep.running mode uses flag 4 (“Inhibit suspending the session or computer”), and in keep.presenting mode uses the flag 8 (“Inhibit the session being marked as idle”). To deactivate the mode, calls the Uninhibit method of the org.gnome.SessionManager with the cookie.

  • Multiprocess safe?: Yes

  • What if the process holding the lock dies?: The lock is automatically removed.

  • How to check it?: You may check the list of inhibitors using the GetInhibitors method, which gives you list of object paths like ["/org/gnome/SessionManager/Inhibitor20"]. Then you can use the GetAppId, GetFlags and GetReason methods on the org.gnome.SessionManager.Inhibitor interface of the listed objects on the org.gnome.SessionManager service to translate that into something meaningful. A good tool for this is D-Spy. Alternatively, you could monitor your inhibit call with dbus-monitor.

  • Requirements: D-Bus, GNOME Desktop Environment with gnome-session running. The exact version of required GNOME is unknown, but this should work from GNOME 2.24 (2008-09-23) onwards. See version history of org.gnome.SessionManager.xml. At least this and this mention GNOME 2.24.

  • Post Keepawake Behavior: Resetting type (GNOME 47, #471).

  • Tested on: Ubuntu 22.04.3 LTS with GNOME 42.9 (PR #138 by fohrloop).

May slow down system if called repeatedly

If used thousands of times really fast, may slow down system. See: wakepy/#277

SetThreadExecutionState#

Windows will not lock the screen automatically if Screen Saver settings do not require it

Since this method prevents sleep, screen can be only locked automatically if a screen saver is enabled and it set to ask for password. See this for details.

  • Name: SetThreadExecutionState

  • Modes: keep.running, keep.presenting

  • Introduced in: wakepy 0.1.0

  • How it works: It calls the SetThreadExecutionState function from the Kernel32.dll with ES_CONTINUOUS and ES_SYSTEM_REQUIRED flags when activating keep.running mode, and additionally ES_DISPLAY_REQUIRED flag when activating keep.presenting mode. It then uses the ES_CONTINUOUS flag for deactivating.

  • Wakepy specialities: Starting with wakepy 0.9.1 you can have multiple modes (same or different) activated within the same python thread without them interfering with each other on activation or deactivation, as wakepy creates a separate worker thread for the single purpose of setting and keeping the thread execution flag each time you activate a mode with the SetThreadExecutionState wakepy.Method.

  • Multiprocess safe?: Yes

  • What if the process holding the lock dies?: The lock is automatically removed.

  • How to check it?: Run powercfg /requests in an elevated cmd or Powershell.

  • Requirements: Windows XP or higher (client), Windows Server 2003 or higher (server), as mentioned here.

  • Post Keepawake Behavior: Up to Windows 10: Non-Resetting with about 2 minutes of Post-Exit Inhibit. The post-exit inhibit time seems to be a bit random, but it’s very likely that any post-exit inhibit duration is between 1:30min and 3:30min (See: #450). Starting from Windows 11: Just Non-Resetting, without post-exit inhibit. The post-exit inhibit behavior is also “documented” on this question on learn.microsoft.com (Sep 8, 2022), where the answer said: “Prior to Windows 11 power requests were held an additional 2 minutes after they were dropped by the application. […] This behavior was removed in Windows 11 and now systems are eligible to sleep as soon as the last power request is dropped”.

  • Tested on: Windows 10 Pro version 22H2 build 19045.332 with and without Screen Saver + ScreenSaverIsSecure set in settings, Windows 10 Enterprise version 22H2 build 19045.3803 with Group Policies enforcing ScreenSaverIsSecure (Issue #169 by fohrloop).

How to check if Windows will lock the screen automatically when using SetThreadExecutionState

There are two ways how a Windows system might automatically set a screen lock

  1. When resuming from sleep, if “Require sign-in when PC wakes up from sleep” -setting is set.

  2. When Screen Saver idle timeout is reached and it has set to have password protection in the Lock Screen Setting or that is enforced by a Group Policy.

if you want to check if your system will sleep automatically when using this method, you may either check the ScreenSaverIsSecure, ScreenSaveActive and ScreenSaveTimeout from “HKCU:\Control Panel\Desktop” and “HKCU:\Software\Policies\Microsoft\Windows\Control Panel\Desktop”, or use the following python snippet:

import ctypes

SPI_GETSCREENSAVESECURE = 0x0076
SPI_GETSCREENSAVEACTIVE = 0x0010
SPI_GETSCREENSAVETIMEOUT = 0x000E

retval = ctypes.c_long()
pvparam = ctypes.byref(retval)

result = ctypes.windll.user32.SystemParametersInfoW(SPI_GETSCREENSAVEACTIVE, 0, pvparam, 0)
print('SPI_GETSCREENSAVEACTIVE', retval.value)

result = ctypes.windll.user32.SystemParametersInfoW(SPI_GETSCREENSAVESECURE, 0, pvparam, 0)
print('SPI_GETSCREENSAVESECURE', retval.value)

result = ctypes.windll.user32.SystemParametersInfoW(SPI_GETSCREENSAVETIMEOUT, 0, pvparam, 0)
print('SPI_GETSCREENSAVETIMEOUT', retval.value)
Contents