Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorServiceIdle::IdleService Class Reference

Session idle-management host for Phosphor-based desktop shells. More...

#include <PhosphorServiceIdle/IdleService.h>

Inheritance diagram for PhosphorServiceIdle::IdleService:
[legend]

Signals

void stagesChanged ()
void currentStageChanged ()
void idled (int stage)
 Entered idle stage stage (1-based).
void resumed ()
 Returned to active from any idle stage.
void inhibitedChanged ()

Public Member Functions

 IdleService (QObject *parent=nullptr)
 ~IdleService () override
bool isSupported () const
 Whether the compositor advertises the idle-notification protocol this service builds on.
QVariantList stages () const
 The idle ladder, as a list of { name: string, timeoutMs: int } maps, sorted by ascending timeout.
void setStages (const QVariantList &stages)
 Reconfiguring the ladder to a DIFFERENT one resets the session to active.
bool isArmed () const
 Did the current ladder actually ARM?
int currentStage () const
 0 when active; otherwise the 1-based index of the deepest stage currently reached.
QString currentStageName () const
 Name of the current stage, or an empty string when active.
bool isIdle () const
bool isInhibited () const
int inhibit ()
 Acquire an idle inhibition.
bool release (int cookie)
 Release a previously acquired inhibition.

Detailed Description

Session idle-management host for Phosphor-based desktop shells.

Watches the session for inactivity through a configurable multi-stage timeout policy and inhibits idle on request. It is the policy layer over the raw Wayland clients in phosphor-wayland (IdleNotifier for ext-idle-notify-v1, IdleInhibitor for zwp-idle-inhibit-v1); it composes them rather than binding the protocols itself, so its public surface is a clean Qt/QML type with no Wayland types leaking out.

Configure the ladder with stages (each entry a { name, timeoutMs } map); the stages are sorted by ascending timeout. As inactivity grows, currentStage advances (1-based) and idled(stage) fires; the first activity resets to active (currentStage == 0) and fires resumed(). The shell decides what each stage does (dim, lock, display-off); this service only reports which stage is active.

inhibit() / release(cookie) reference-count idle inhibition; while inhibited the ladder is disarmed and reports active. It is mechanism, not policy: it ships no default stages.

Constructor & Destructor Documentation

◆ IdleService()

PhosphorServiceIdle::IdleService::IdleService ( QObject * parent = nullptr)
explicit

◆ ~IdleService()

PhosphorServiceIdle::IdleService::~IdleService ( )
override

Member Function Documentation

◆ currentStage()

int PhosphorServiceIdle::IdleService::currentStage ( ) const
nodiscard

0 when active; otherwise the 1-based index of the deepest stage currently reached.

◆ currentStageChanged

void PhosphorServiceIdle::IdleService::currentStageChanged ( )
signal

◆ currentStageName()

QString PhosphorServiceIdle::IdleService::currentStageName ( ) const
nodiscard

Name of the current stage, or an empty string when active.

◆ idled

void PhosphorServiceIdle::IdleService::idled ( int stage)
signal

Entered idle stage stage (1-based).

◆ inhibit()

int PhosphorServiceIdle::IdleService::inhibit ( )
nodiscard

Acquire an idle inhibition.

Returns a cookie to release it with; idle is inhibited (the ladder disarmed) while any cookie is held. Retain the cookie: discarding it leaks the inhibition for the process lifetime (cookies are never reused).

◆ inhibitedChanged

void PhosphorServiceIdle::IdleService::inhibitedChanged ( )
signal

◆ isArmed()

bool PhosphorServiceIdle::IdleService::isArmed ( ) const
nodiscard

Did the current ladder actually ARM?

isSupported() answers "does the compositor speak the protocol". This answers "did we manage to use it", and the two genuinely differ: arming needs a seat with its input devices advertised, and a client that starts while the compositor is still bringing the seat up arms nothing at all. Idle detection is then dead for the session while isSupported() cheerfully keeps saying true. False for an empty ladder (nothing is being watched). A caller that wants to survive that race must be able to ask, and to rebuild: clear the ladder and set it again, which is a real change and so is not swallowed by the no-op rule above.

◆ isIdle()

bool PhosphorServiceIdle::IdleService::isIdle ( ) const
nodiscard

◆ isInhibited()

bool PhosphorServiceIdle::IdleService::isInhibited ( ) const
nodiscard

◆ isSupported()

bool PhosphorServiceIdle::IdleService::isSupported ( ) const
nodiscard

Whether the compositor advertises the idle-notification protocol this service builds on.

When false the service constructs but stays inert.

◆ release()

bool PhosphorServiceIdle::IdleService::release ( int cookie)

Release a previously acquired inhibition.

Returns true if cookie was held; a no-op returning false for an unknown or already-released cookie.

◆ resumed

void PhosphorServiceIdle::IdleService::resumed ( )
signal

Returned to active from any idle stage.

◆ setStages()

void PhosphorServiceIdle::IdleService::setStages ( const QVariantList & stages)

Reconfiguring the ladder to a DIFFERENT one resets the session to active.

The old sources are destroyed and new ones armed, and a compositor arms a fresh notification from the active state — so if the session was idle, resumed() fires and currentStage returns to 0. Passing an empty list therefore both disarms idle detection AND releases an already-idle session. That is contract, not incidental behaviour, and it is pinned by IdleStateMachine's clearStagesWhileIdleResumes test: whatever a consumer gated on idleness must be released when idle detection goes away, or it stays gated on a fact nobody is reporting any more.

Setting the ladder it already has is a no-op: it does NOT re-arm and does NOT resume. That is what makes it safe to call on every settings change.

◆ stages()

QVariantList PhosphorServiceIdle::IdleService::stages ( ) const
nodiscard

The idle ladder, as a list of { name: string, timeoutMs: int } maps, sorted by ascending timeout.

Entries with a non-positive timeoutMs are ignored. Build the maps with the StageKey constants above rather than spelling the field names out: they are a wire contract between this library and its callers, and a typo on either side silently produces a zero timeout, which toStages then DROPS — leaving an empty ladder that never fires, with no warning anywhere.

◆ stagesChanged

void PhosphorServiceIdle::IdleService::stagesChanged ( )
signal

The documentation for this class was generated from the following file:
  • phosphor-service-idle/include/PhosphorServiceIdle/IdleService.h