Module power 

What this computer says of itself, for work it may do while you are away (the spam filter’s training by itself: docs/spam-filter.md, “Training by itself”): on mains power or on its battery, saving power or not, idle or in use, its connection metered or not. Each fact is None when this computer cannot tell it (no such service, no answer in time, a system not read here): whoever decides counts an unknown fact as not holding.

Also whether a person is at it now (kept_session, present_of): input within ten minutes, its session not locked. A computer says so in its entry among your devices, and while you sleep a phone’s background steps slow down when nobody is at any computer (docs/android.md, “In the background”).

All of it is read on one thread of its own (watch), every thirty seconds while it is asked for, on one connection per bus kept for the process (made again only once the bus dropped it), and kept: whoever asks reads the kept values (read, supply, kept_power, kept_session) and never opens a bus nor asks it anything. A bus that stops answering after the thread connected only gives its questions up, a second each; one that takes a new connection and never answers is given up after bus::SETUP and holds one thread of its own, never this one nor libdbus’s process-wide locks (the connections are crate::bus’s).

• Linux and the BSDs, over D-Bus: UPower’s OnBattery; power-profiles-daemon’s ActiveProfile, under both of its names (org.freedesktop.UPower.PowerProfiles, the older net.hadess.PowerProfiles); the session’s idle time (the desktop’s org.freedesktop.ScreenSaver, in milliseconds as KDE gives it, GNOME’s org.gnome.Mutter.IdleMonitor) and whether it is locked (both screen savers, logind’s LockedHint; logind’s IdleHint only as a word for idle, since some desktops never set it); NetworkManager’s Metered.
• Windows: GetSystemPowerStatus (its AC line, its battery saver), GetLastInputInfo, and whether the session is locked (WTSQuerySessionInformationW’s WTSSessionInfoEx). The connection’s cost is not read: unknown.
• macOS: IOKit’s power sources, Low Power Mode (as pmset -g says it), CGEventSourceSecondsSinceLastEventType, and whether the screen is locked (CGSessionCopyCurrentDictionary’s CGSSessionScreenIsLocked). The connection’s cost is not read: unknown.
• Android: nothing; a phone never trains, and its own entry says it is in use while Sioul is on its screen.

Modules

imp 🔒

Structs

LinuxAnswers 🔒

What a Linux or BSD desktop’s services answered of its session (imp::session), each none when it did not answer: the desktop’s screen saver (KDE’s, and others of the freedesktop name), GNOME’s idle monitor and screen shield, logind’s hints.

Power

What this computer says of itself now.

Reading 🔒

One reading of the thread: when it began (a press in Sioul made while it was read is newer than it: present_since), the session, the power supply and the connection’s cost.

Session

What the session says of the person at this computer now.

Shared 🔒

What the reading thread and those who ask share: its last reading, and when it was last asked for readings.

Constants

ASK 🔒

How long one question to the system may take.

ASKED_FOR

How long the reading thread goes on after it was last asked (watch, read); past it, it rests until the next ask. The window asks at each exchange, every minute; a process that asked once (sioul watch, whose training asks only when nothing else holds it back) is not read every half minute for days after.

EVERY

How often the reading thread reads everything while it is asked for (watch).

IDLE

How long without anyone’s hands on the computer counts as idle.

KEPT_FOR

How long a reading is kept for (kept_session, kept_power, read): past it, none (the thread held by a bus, or resting), and Sioul running counts, as when nothing is said.

PRESENT

How long without input a person no longer counts as at this computer (present_of).

WAIT

How long read waits for a fresh reading: a few questions to the system, a second each at most, and the connections’ setup.

Statics

BELL 🔒

Rung at each reading kept and at each ask: whoever waits on it looks again.

SHARED 🔒

STARTED 🔒

The reading thread started (start).

Functions

ask 🔒

Readings asked for at now: the thread resting wakes (wanted).

ever_read_within 🔒

read_once_within, on shared and its bell.

fresh 🔒

reading while it is younger than KEPT_FOR at now.

fresh_within 🔒

The reading in shared once fresh (fresh), waited for limit at most, looked at again at each ring of bell; none after it.

idle_of

Idle, from what the session said: locked, idle; else the shortest time without input any source gave (the newest touch wins); nothing said, unknown.

kept_power

The power supply and the connection’s cost as last read (watch); none before the first reading, or once it is KEPT_FOR old. Never asks the system, never waits: for an exchange (the window’s metered).

kept_session

The session as last read (watch) and how long ago that reading began; none before the first, or once it is KEPT_FOR old (a bus that stopped answering, the thread resting). Never asks the system, never waits.

linux_session 🔒

The session as a Linux or BSD desktop’s answers say it, now the real clock since the epoch: locked when a locker says so and none says otherwise, disputed when they disagree (logind’s hint left locked by a locker that died, while the desktop’s own screen saver says unlocked); the shortest time since input any of them gave.

macos_session 🔒

The session as macOS says it: the seconds since its last input (CGEventSourceSecondsSinceLastEventType; none from a value that is no time), and whether its screen is locked.

metered_of

NetworkManager’s Metered (NMMetered): yes or guessed yes, metered; no or guessed no, not; unknown (0) or anything else, unknown.

present_of

Whether a person is at this computer now: its session locked, no; else a press in Sioul (its window, do-not-disturb’s switch) less than PRESENT ago (pressed), yes, whatever the system says of input; else input less than PRESENT ago, as the session says, also when its sources disagree on the lock (Session::disputed: input alone says it); nothing said of input, unknown. Unknown is never “nobody”: Sioul running then counts as someone at it, as before (devices::others_in_use).

present_since

present_of, from the session as last read (kept_session: the reading and how long ago it was made; none when there is none fresh enough) and the last press in Sioul (how long ago): a press made since the reading counts whatever the reading said, its lock included (someone unlocked the computer to make it); an older one as present_of reads it. No reading, a press within PRESENT says someone, and nothing else says anything (unknown: Sioul running counts).

read

Every fact, as the reading thread read it (watch, started and asked): its last reading while younger than KEPT_FOR, else the next one, waited for WAIT at most (the first of this process, or the thread asked again after a rest: ASKED_FOR); none by then, nothing said. Never opens a bus nor asks it anything itself; for work that may wait on a thread of its own (the spam filter’s training), never for an exchange (kept_power).

read_once_within

Whether the reading thread kept a reading yet in this process, its first waited for limit at most while there is none (the window’s first exchange, metered: a connection not read yet counts as metered).

reading_of 🔒

A reading by read, timed from when it began (began), not from when it came back: a press made while a slow reading said locked is newer than it (review of battery part C, G6).

start 🔒

The reading thread, started once, its imp::Reader made on it by reader: a reading, kept and rung; EVERY on, the next, once someone asked within ASKED_FOR (wanted), else at the next ask. Nothing started where nothing is read (a phone).

supply

Its power supply alone (mains, saving power), as read gives it: what a training running asks every half minute.

wanted 🔒

Whether the reading thread goes on reading at now: asked within ASKED_FOR.

watch

Starts, once in this process, the thread that reads everything on its own connections to this process’s buses (imp::Reader) every EVERY while asked within ASKED_FOR, and keeps the last reading; and asks it. Nothing else in the process asks the system for these: an exchange, a start, Sioul closing and the training read what is kept.

watch_on

watch, on the buses at these D-Bus addresses (none: that bus not read): stand-ins, so that a test never reads the session or the system of whoever runs it. Only the first start in a process counts; elsewhere than on Linux and the BSDs, nothing is read over D-Bus and they are not used.

windows_flags 🔒

The flags of WTSSessionInfoEx’s answer, as Windows lays it out (WTSINFOEXW): its level (a DWORD, 1), then, 8-aligned for the times that follow, its session’s id, state and flags (each 4 bytes): the flags at byte 16. None for another level, or an answer too short to hold them.

windows_locked 🔒

Windows’ word on a session’s lock (WTSINFOEX_LEVEL1_W::SessionFlags): WTS_SESSIONSTATE_LOCK (0), locked; WTS_SESSIONSTATE_UNLOCK (1), not; anything else (WTS_SESSIONSTATE_UNKNOWN), unknown.

windows_session 🔒

The session as Windows’ answers say it: the tick counts now and at the last input (GetTickCount, GetLastInputInfo; none when it failed; both wrap alike every 49.7 days), and WTSSessionInfoEx’s answer (none when Windows gave none).