Module notify 

The one exception to the admin windows: a quiet desktop notification for a verified code, with the code in it (docs/porch.md, “Right now”); a gentle reminder; new mail at the times it may come, once per batch (docs/porch.md, “Notifications”); and the time running, while a focus session runs (docs/tasks.md).

On Linux and the BSDs each notification goes to the session’s notification server over a D-Bus connection of its own, made by crate::bus: a session bus that takes it and never answers holds one thread of its own, never the caller nor libdbus’s process-wide locks (review of battery part C, G1). Its call is the one notify-rust’s Notification made before 13 October 2026, argument for argument (notify_message), but for its urgency, said once (notify-rust’s hints are a set, where a mail’s normal urgency and the critical one it started from were two, sent in no fixed order). Windows and macOS: notify-rust.

A dose’s reminder (remind_dose) is built on one rule: never invite a second dose, and when this device cannot know, say the doubt (docs/health.md, “Knowing”). What became of its first try is said in three ways, recorded as such: shown (the server answered while the tick waited), not shown (surely not gone out), or maybe (sent, its fate not known), which a phone’s alarm then reminds with the doubt said first. Whatever shows late on this computer (a try after the first, or the first answered late) says the doubt first; tries after the first end before the phone’s alarm could ring.

Structs

Again

What a dose’s reminder does after its first try (remind_dose), Linux and the BSDs; elsewhere the first try is the only one:

Lasting 🔒

A lasting notification, across its connections: what it says, whether that changed since it was last sent, the server’s number for it (0 while none shows), when the server last refused it.

Notice 🔒

A notification as Sioul sends it on Linux and the BSDs (notify_message): its words, its icon (a theme’s name), its urgency, its buttons as (key, label).

Ongoing

The notification of something going on, the time running while a focus session runs (docs/tasks.md): shown until it is closed, changed in place, its buttons pressed any number of times. Its own thread holds the D-Bus connection that shows it, and listens there: the server tells a press to that connection alone (Plasma addresses it). Resident, kept when a button is pressed; at normal urgency, for Plasma shows a low one nowhere unless told to; without sound. A server that keeps what it shows (“persistence”: its history, its tray) takes it there after its popup, buttons alive; elsewhere it does not expire. No session bus, no server: nothing shows, nothing breaks. Dropped, it is taken away.

Said 🔒

What a lasting notification says: its buttons as (key, label), “default” for a click on it.

Sending

A dose’s reminder under way (remind_dose): what became of its first try, said by its thread while the tick waits; once the tick stopped waiting (outcome returned, or this dropped), what shows is late.

Shown 🔒

A notice sent: the connection that sent it (kept: the server tells a press to it), what it hears, the answers to its own calls (Replies), the server’s number for it (0 while not known), what the server reads.

Slot 🔒

Where a first try’s outcome is left for the tick, and whether the tick still waits for it.

Enums

Change 🔒

Going

Which notice is about to go (DoseRecord::going).

Heard 🔒

What the server said, read between two looks.

Late

Why a reminder shows late (Going::Late): its words differ.

Outcome

What a dose reminder’s first try became, as the tick records it.

Reply 🔒

An answer to a call of this connection’s own sent without waiting (dbus::channel::Sender::send): its return, or the error the bus or the server gave: whether it says the call reached nobody (undelivered), and in a few words.

Say

What a notice about to go says (DoseRecord::going).

Served 🔒

What became of a lasting notification on one connection (served): taken away, or its connection lost (made again, the notification shown again in place of its number, when the server still knows it).

Tried 🔒

What one try of a dose’s reminder became.

Constants

ASKED 🔒

How long the server may take to answer about a notification (notify-rust’s own wait).

ASKED_AGAIN 🔒

A notification the server refused (one starting with the session, after Sioul) is asked again this often.

BUNDLE_ID

Sioul’s bundle id on macOS, as packaging/macos/Info.plist names it (CFBundleIdentifier). macOS shows a notification as coming from the application whose id it is given; without one, notify-rust’s macOS side (mac-notification-sys) names another application.

CLOSE_LATE 🔒

How long a lasting notification taken away while its Notify is not answered waits for that answer, its number, to close it (close_lasting): a server seconds late still gets it closed.

CRITICAL 🔒

DESKTOP_ENTRY 🔒

Sioul’s desktop file, named on each notification (“desktop-entry”): the desktop knows them as Sioul’s, and lists Sioul in its notification settings (Plasma’s “Show in do not disturb mode”, for the doses during a pause: docs/pauses.md).

FIRST_TRY

How long the tick waits for what became of a dose reminder’s first try (Sending::outcome): its whole first try fits in it (TRY), the connection’s setup, its two matches, the server’s two answers.

LISTENED 🔒

How long a lasting notification’s thread listens to the server before it looks at what Sioul asked: a change shows within it.

LISTEN_LATE 🔒

How long a dose’s notice sent and not answered is still listened for (wait_late): its answer, however late (a bus or a server stalled for minutes, hours), says it is shown, and it is then said again in place, the doubt first, or taken away, never left in its first words after another device reminded the dose. A day: past it, the dose is long asked about as one of the past.

LOOK 🔒

How often a dose’s reminder still shown looks whether its dose was marked or answered elsewhere (wait_for_press): the sharing reads the others each minute.

MATCH 🔒

How long each of a dose reminder’s two matches (its button, its close, heard on its connection) may take on its first try: the bus answers them at once.

MATCH_AGAIN 🔒

Each match’s wait on a try after the first (TRY_AGAIN).

NORMAL 🔒

Urgencies, as the specification numbers them: normal, and critical (what Sioul sends always gets through: it filters its own notifications already).

SERVER 🔒

The notification server, on the session bus.

SERVER_PATH 🔒

SHOWN 🔒

How long the notification stays: about the life of a code.

TRY 🔒

What a dose reminder’s first try spends at most, its setup and all: the tick’s wait (FIRST_TRY) less half a second, for its word to reach the tick.

TRY_AGAIN 🔒

The same for a try after the first, which no tick waits for: a slow bus (each answer seconds late, a machine swapping) still shows it, late, as a connection of dbus-rs’s own waits (five seconds a call).

Traits

DoseRecord

What a dose’s reminder records, and asks, as it goes (docs/health.md, “What became of a reminder”), so that another device knows what this one did before it reminds the dose itself: each notice recorded before it goes (going), what became of it after. Its own device’s entry alone (sioul_core::dose_reminders).

Functions

again_in 🔒

How long a dose’s reminder waits before its try after tries others: five seconds for two minutes (a bus that stalled a while: shown soon after it answers), then half a minute.

answer_by 🔒

The answer to serial, hearing on bus all that comes until until; none by then, or the connection gone.

body_text 🔒

A body as the notification server reads it. Most read markup there (“body-markup”: <b>, <a href>, <img src>), and bodies carry a mail’s or a site’s words: there, &, < and > are written as entities, so that the words show as they came and nothing in them is a link or a picture to fetch. A server that reads no markup shows the text as it is. The summary is plain text for every server (the specification), and goes as it is.

capabilities 🔒

What the server reads (GetCapabilities), asked limit at most; none: not asked, or no answer (read as markup: entities at worst).

close_lasting 🔒

Taken away: by its number; a Notify not answered yet, its answer waited for first (CLOSE_LATE at most: its number), so that it does not stay (the fifth review’s L4); the close of a session goes on meanwhile.

code

Shows a code: title says what and from whom, body the code and how long it lasts. No sound. With copy, the notification offers a button labelled with its text, and its action runs when the button is pressed; the notification then lives on its own thread, which waits for the button.

first_try 🔒

A dose reminder’s first try, on its own thread: recorded before it goes, its outcome left for the tick (told), then as Again says. Sent while the tick waits, in its own words; once the tick stopped waiting, in late words (the doubt first), or not at all (no longer to remind). Answered late, said again in place, the doubt first (shown_late).

heard_replies 🔒

The answers to the calls sent without waiting on bus, heard from now on.

lasting_message 🔒

The lasting notification’s Notify, in place of id if not 0.

listened 🔒

What the server says of notifications, heard on bus from now on: buttons pressed, notifications closed (Heard), kept in heard.

listened_within 🔒

listened, each of its two matches waited for each at most (a dose’s first try fits in the tick’s wait: TRY).

mail

New mail at the times it may come (docs/porch.md, “Notifications”): one notification for the batch, no sound, with one button (“Open”: the Porch) whose action runs when pressed. At normal urgency, unlike codes and reminders: the desktop’s own do-not-disturb holds it; but at critical urgency when someone Always through is in it (through), which passes it (docs/attention.md, Q10).

notify 🔒

Shows notice. Without pressed, on the caller’s thread, the server’s refusal said. With it, on a thread of its own, which keeps the connection that showed it (the server tells a press to that connection: Plasma addresses it) and waits there (wait_for_press).

notify_message 🔒

The Notify call, as notify-rust’s Notification made it, argument for argument: “Sioul”, the notification it replaces (0, none), the icon, the title as it is, the body as the server reads it (body_text), the buttons, the hints (no sound, Sioul’s desktop file, the urgency, each once), ten minutes (SHOWN).

one_button 🔒

notice with one button at most, keyed “copy” (code, remind, mail): its action runs when it is pressed.

ongoing

Shows the notification of something going on. actions are its buttons as (key, label), “default” for a click on it; on_action runs with the key of each one pressed, on the notification’s own thread.

pressed_choice

Which of a notice’s buttons a press names (remind_offering): “choice-1” the second; a click on the notice itself (“default”) the first; none when it closed unanswered (“__closed”) or for anything else.

remind

A gentle reminder: one notification, no sound, with one button whose action runs when pressed (a dose’s own: remind_dose).

remind_choices

A gentle reminder with several buttons, each its label and its action: the one pressed runs (the night’s notice: “Close the day” and “Options…”).

remind_dose

A dose’s reminder (docs/health.md, “Knowing”): what remind shows with its button (“Taken”), on a thread of its own, whose first try fits in FIRST_TRY and says what it became (Sending::outcome); then as Again says. “Taken” runs once, however late it is pressed while the notice lives.

remind_offering

A gentle reminder with its buttons wherever the system carries them, each its label and its action (the end of work’s notice and the night’s: docs/reviews.md). On Linux and the BSDs as remind (one button) or remind_choices (several) show them. On macOS with NSUserNotification’s own: the action button, or “Options” and its list when there are several; a click on the notice itself is its first button’s. Sent and waited for on a thread of its own, until a press or until the notice leaves the Notification Center (macOS hands the press to the main thread, which Qt’s loop runs). The doses’ reminders stay as remind shows them. On Windows, the words alone (the window shows these through Sioul’s icon in the tray instead, a click opening the first button’s); on Android, none (Java’s).

said 🔒

A D-Bus error in a few words: its message, else its name.

said_now 🔒

notice’s words as record says them now, recorded first as about to go (DoseRecord::going); false when it is no longer to remind.

send 🔒

notice shown on bus, its answer waited for ASKED: the server’s number for it.

serve 🔒

A lasting notification’s thread: what Sioul asks shown, what the server says heard, until it is taken away. Its connection is made again while the bus does not give one (a stall: bus refuses at once meanwhile, five seconds apart, bus::SETUP) and once it is lost, rather than the notification being lost for the session (review of battery part C, L4); what Sioul asks meanwhile is kept, the last of it, and a close ends it.

served 🔒

A lasting notification on connection: what Sioul asks shown, what the server says heard, until it is taken away or the connection is lost. Each Notify goes without waiting, its answer heard as it comes: while one is not answered, none other is sent, so that a server answering late never shows it twice (each shown with no number to replace, neither taken away: review of battery part C, L1); its late answer gives the number, and what changed meanwhile goes in its place.

session 🔒

A connection to the session’s bus, made by crate::bus (bus::SETUP at most).

session_within 🔒

The same, made within limit.

show_again 🔒

A dose’s reminder tried again after a first try that did not go out, the doubt first, until Again::end, then no more (DoseRecord::over): the bus first (a stalled one refuses at once, bus, and nothing else is read meanwhile), then the server, its words read last, just before it goes, recorded as going (none: no longer to remind, and no more tries). None during Again::quiet (a phone’s alarm rings then): promised before it begins (DoseRecord::pause), the tries resumed after it while still to remind. Sent and not answered in time: never again (wait_late).

shown_late 🔒

A dose’s reminder known shown late (answered late, or after the tick stopped waiting). Its words read first (DoseRecord::going; they depend on the record, which says it shown right after): still to remind, it is recorded shown (DoseRecord::shown) and said again in place with the doubt first (Late::Unconfirmed: “was not confirmed in time”), unless it says so already, was closed meanwhile (seen), or its “Taken” was pressed meanwhile (the press runs after, wait_for_press: never shown again over it). The server’s answer to that Notify gives its number from then on (GNOME gives a new one to a notice no longer shown). No longer to remind (marked, reminded elsewhere, kept elsewhere now), it is taken away, never recorded shown: another device reads it sent, maybe shown, and says so.

told 🔒

A first try’s outcome left for the tick: whether the tick still waited for it (else what shows now shows late).

try_once 🔒

One try of a dose’s reminder: the connection (made now, within the first try’s TRY; or bus, a try after the first, within TRY_AGAIN), its two matches, what the server reads, then its words as they are now (words: shown late, the doubt first; false, no longer to remind), then the Notify, sent only with its own wait (ASKED) still ahead, and that wait. Not gone out when anything before the Notify fails or there is no time left for it; sent and not answered in time, maybe.

undelivered 🔒

Whether a D-Bus error says the call reached nobody: no server owns the name. Any other (no reply, the server gone, the server’s own error) may come after the server took the notice and showed it (the sixth review’s L2).

wait_for_press 🔒

A shown notice’s button waited for on its connection: pressed runs with the key of the first one pressed, and the wait ends then, or when the notification closes, or the connection goes. What it heard before its number was known is read now. A dose’s reminder (record) is taken away once its dose is marked or answered anywhere read here, looked at each LOOK (review of battery part C, the fifth review’s L2).

wait_late 🔒

A notice sent and not answered in time: its answer still heard on its connection, however late (LISTEN_LATE), never sent again; answered, it was shown, late (shown_late), and its button counts. Refused late, or its connection gone (the server, or the bus, gone): it may have shown, its record says so still, and it is tried again, the doubt first, while its grace lasts (show_again: the sixth review’s M2).

waited_for 🔒

Whether the tick still waits for a first try’s outcome (Sending).

Type Aliases

Pressed 🔒

What runs with the key of the button pressed.

Replies 🔒

The answers to this connection’s calls sent without waiting, by serial, kept as they come, late ones too (heard_replies).