Platform and Ownership

Introduction

The platform is the object an application is built against. It is the one place the framework meets the operating system, and it is where everything that is process-wide lives: the connection to the display server, the timers, the clipboard, the directory watches. An application holds exactly one, builds it first and destroys it last, and everything else in the process - the context, the forms, every control - stands on it.

import ClaFi.Platform.Windows;   // Win32Platform, Win32Application
import ClaFi.Platform.Wayland;   // WaylandPlatform, WaylandApplication

Most code never names the platform. A control reaches what it needs through its context - the clipboard through formContext().clipboard(), the animation controller through appContext().animator() - and the framework's own services reach their owner through one of two seams described in Reaching the Platform From Below. This manual is for the reader who wants to know what stands where, in what order it is built and torn down, and how to add a service of their own without breaking that order.

One rule is worth carrying from the start: nothing framework-wide is a static. Every object that serves the whole process has an owner, the owner is the platform or the application's context, and the object is built and destroyed at the moment its owner's member order says. A service that cannot hold a reference to its owner - a hook with no object in hand - reaches it through a standing pointer the owned object sets and clears, and a hook that finds none standing has found a broken order and says so.

Basic Usage Example

An application is Application<Platform, GpuBackend>, or a class derived from it, built from the platform's Params. The second argument names the GPU backend the application offers and may be left out, which offers none. The entry point is the whole of what a program knows about its platform:

// Win32 - Direct2D beside the CPU backend
int __stdcall wWinMain(HINSTANCE hInstance, HINSTANCE, wchar_t*, int)
{
    using namespace ClaFi;

    Themes_App::ThemesApplication<Win32Platform, Direct2DBackend> app{ { hInstance } };
    return app.run();
}

// Wayland - no GPU backend is named, because this platform has none
int main()
{
    using namespace ClaFi;

    Themes_App::ThemesApplication<WaylandPlatform> app{ WaylandPlatform::Params{} };
    return app.run();
}

Two aliases name the common pairings: Win32Application is Application<Win32Platform, Direct2DBackend> and WaylandApplication is Application<WaylandPlatform>. The CPU backend is the core's own and every application has it, so naming no GPU backend is an answer rather than a gap: Application<Win32Platform> draws on the CPU and offers nothing to turn on. One that names Direct2D carries both and starts on whichever its config holds - see The Backend.

The Two Halves of a Platform

A platform is two classes in a base-derived pair. Platform, declared in the Context module, is what the rest of the framework sees and is the same on every platform. Win32Platform and WaylandPlatform derive from it, one per build, and are what the entry point names. The base is the contract; the derived class is the owner.

Platform, the Neutral Half

Platform lives in ClaFi.Core.Context.FormContext and carries three kinds of member:

The base holds a reference rather than the clipboard itself because of order: a base is built before any member of the derived class, and on Win32 the clipboard has to come after the OLE apartment the windows manager opens. So the derived class declares the clipboard where the order needs it and hands the base its address - before the clipboard is built, which a reference may be, nothing reading through it until the platform stands whole.

The Platform Built for the Display Server

Win32Platform and WaylandPlatform are the owners. Each derives from Platform and from one further interface that says what its platform layer offers to services standing below the context - the subject of The Empty Name and What Stands Behind It:

export struct Win32Platform
    :
    public Platform,
    public PlatformImplementation::Windows::IMessageWindowFactory
{
    ...
};

export struct WaylandPlatform
    :
    public Platform,
    public PlatformImplementation::Wayland::IDisplayAccess
{
    ...
};

What each owns, and in what order, is the next section. The rule they share: a platform member is declared after everything it needs and before everything that needs it, and what the platform owns is reached through the platform - or, where a hook has no object in hand, through the standing pointer the owned object publishes.

Params

Each platform declares a Params struct, and IsPlatform asks for nothing more than that a platform is constructible from one. It is what the entry point has and the platform wants:

What the Platform Owns

C++ builds members in declaration order and destroys them in reverse, and that is the whole of the lifetime machinery here. Each platform lists its members in the order they depend on each other, the comment on the list says why, and nothing else states an order anywhere.

Win32Platform

private:
    Params m_params;
    PlatformImplementation::Windows::WindowsManager m_manager{ m_params.appInstance };
    PlatformImplementation::Windows::TimerManager m_timers{ m_manager };
    Transfer::Clipboard m_clipboard{ *this };

WaylandPlatform

private:
    PlatformImplementation::Wayland::DisplayManager m_display{};
    PlatformImplementation::Linux::TimerManager m_timers{};
    PlatformImplementation::Linux::DirWatchManager m_dirWatches{};
    PlatformImplementation::Wayland::PollSource m_timerSource{ m_display, m_timers.eventFd(), ... };
    PlatformImplementation::Wayland::PollSource m_dirWatchSource{ m_display, m_dirWatches.notifyFd(), ... };
    Transfer::Clipboard m_clipboard{ *this };

Order Is the Design

Two things follow from letting member order carry the lifetime, and both are deliberate.

First, there is no initialize() or finalize() on a platform. A member's constructor is its initialisation and its destructor its finalisation, and a member declared in the right place needs neither called. A separate finalisation step is for the case where something must happen while a later member is still standing, and no member of either platform has that case: the Win32 clipboard flushes in its own destructor, which runs before the manager's, and that is the order it wants.

Second, the loop names none of what it polls. On Wayland the display would otherwise have to know the timer and the watch managers, which would put them under it in the module graph and above it in the ownership order at the same time. Instead the display offers addPollSource and removePollSource, and the platform - which owns both the display and the managers - registers each descriptor through a PollSource whose lifetime is the registration.

Where the Platform Stands in an Application

First Up, Last Down

Application<Platform, GpuBackend> holds its platform in a base, not a member:

template <IsPlatform PlatformType>
class PlatformHolder
{
protected:
    PlatformType m_platform;
};

export template <IsPlatform PlatformType, IsOptionalGpuBackend GpuBackend = void>
class Application : private PlatformHolder<PlatformType>, public ApplicationBase
{
    ...
};

Bases are built in declaration order and destroyed in reverse, so the platform is built before ApplicationBase - and with it the AppContext, the config and the ThemesManager with its directory watch - and destroyed after them. Everything an application owns is built on a standing platform and goes down on one. A UiTimer stopped by a dying member finds the timer manager up; a directory watch removed by a dying themes manager finds its manager up; a form's window is destroyed while the windows manager still holds its class.

The Whole Lifetime

From the entry point's braces to their close, in order:

AppContext

AppContext is what a form or a control means by "the application". It holds the platform by reference and hands it out as platform(), and it owns what the application runs for itself rather than what the platform makes from the operating system: the AnimationController, as animator(), and the UpdateCheck, as updateCheck(). The animation controller belongs here rather than to the platform because it is the application's - every control's state fades, every glide, the theme crossing - stepped by one UiTimer that the platform's timer manager serves. Its owner has to stand below the platform and above every control, which is exactly where the context stands.

The update check holds a WebFetch while it asks: one request on a thread of its own, answered on the UI thread through a UiTimer. A fetch cancels its request and joins its thread in its destructor, and the context goes before the platform, so the timer it stops on the way out finds the timer manager up.

A FormContext holds a const Platform& and hands out the one thing a control asks the platform for directly, the clipboard, as clipboard(). It is not const: the clipboard is the process's state rather than the context's, and a copy made from a const context is still a copy.

The Backend

The platform makes a form's window; a backend draws into it. A form asks the context for one as it is built - AppContext::createBackend(window, size) - and is handed the GPU backend the application named while GPU acceleration is on, the CPU backend otherwise. The two kinds are built from different things, and a concept states each:

Besides its size, a backend is told one thing about its window: whether the window carries an alpha channel, so that a frame starts from nothing where the pixels outside a rounded corner are read.

The choice is made in the application's type. Application is a template and a form is not, so it travels down as a function pointer - gpuBackendFactory<GpuBackend>(), null where none was named - and AppContext::gpuAvailable() is that pointer's answer. Where there is one, the config's Performance section holds a GpuAcceleration value, on by default, and the Settings page shows the check that writes it; a change reaches every window at the top of its next frame, and the window's canvas lets go of everything the old backend held. Where there is none, neither the section nor the check exists.

Nothing else in the platform depends on which backend draws, and nothing in a control does. What the two draw, and where they still differ, is the Graphics manual's.

Reaching the Platform From Above

Code above the context - forms, controls, an application's own pages - never names Win32Platform or WaylandPlatform. It reaches what it needs through the context it already has, and the context knows only Platform.

Windows

A form asks for its window in its own member initialiser, through the context's platform:

std::unique_ptr<IPlatformWindow> m_window{
    m_appContext.platform().createWindow(*this, m_windowRole, popupTargetForm())
};

createWindow is the virtual every platform answers. The derived platform answers with a FormWindow made from what it holds - the windows manager on Win32, the display on Wayland - and hands that to the window, so no window reaches for it by any other route. A popup is handed its parent's window the same way, through the parent form. WindowRole says what kind of window: Dialog, Menu or Tooltip, and nothing else.

Window Opacity

A window's opacity is a byte on its IPlatformWindow - alpha() and setAlpha(ColorByte) - applied to the whole window at once. A tooltip fades in and out this way, stepping the byte on AnimationSlots::formAlpha. Each platform applies the value where it costs least:

Zero takes a Wayland window off the screen on either path: a frame nobody can see is not worth drawing, and an unmapped window is how a tooltip says it is not there.

The Clipboard

The clipboard is formContext().clipboard(), a Transfer::Clipboard&. A copy puts a package on it with the input event that asked; a paste asks it for an offer:

// a copy, from a handler that has the click's stamp
Transfer::Source source{};
source.add<Transfer::PlainText>(selectedText());
formContext().clipboard().set(std::move(source), stamp);

// a paste
if (Transfer::Offer* offer = formContext().clipboard().offer())
{
    if (const std::optional<std::wstring> text = Transfer::take<Transfer::PlainText>(*offer))
        insert(*text);
}

// what to connect to instead of polling - scoped, because the clipboard outlives the listener
ScopedEventConnection watch{ formContext().clipboard().events()
    .connect<Transfer::ClipboardChangeEvent>([&](Transfer::ClipboardChangeEvent&) {
        refresh();
    }) };

Where only a form is at hand, form->context().clipboard() is the same object. The clipboard's own manual is the Transfer footnote under Source/.seedocs/footnotes; what matters here is its place: one per process, the platform's member, alive from before the first window to after the last.

Animations

A control runs its animations through Control::animate, which reaches the application's controller through the control's form:

animate(AnimationSlots::expander, m_expandedFactor, target, [this](AnimateParams& params) {
    m_expandedFactor = params.value;
    invalidateChevron();
});

stopAnimation(AnimationSlots::scroll);   // one slot
stopAnimations();                           // every slot of this control

animator() answers the controller, or null while the control stands in no form - there being no application to reach then. animate on a control in no form applies the end value at once through the same callback: nobody sees an unattached control, and the end value is what it is drawn from once attached. A form reaches the controller as appContext().animator(); something that is not a control - the grid's cell highlights - takes it from the control it belongs to and answers the null the same way.

What the Platform Reports

The platform reports what the user does to the form whose window it happened in, through IForm: a pointer move, a press, a wheel, a key, a side button. The form turns each report into the framework's input state, which lives in Input - one per application rather than one per form, since the focus leaves one window as it arrives in another.

The Input Controllers

The mouse and the keyboard are each an InputController: whether it drives the input, and a factor that follows that through a fade of its own. Code outside Input reads them and never writes them:

const InputController& mouse = Input::mouse();
const InputController& keyboard = Input::keyboard();

bool byKey = !mouse.active();         // whether a key did what is being handled
float ringShare = keyboard.factor();  // active() through its fade, from 0 to 1

What the form is told switches them:

So both are on only after a modifier, until the next pointer report or key, and the one state that cannot occur is both off. A modifier names no destination - it qualifies the click or the key that follows, and the pointer is still where the user left it. Two reports switch nothing: a held key's repeats, and the first move a form hears since the pointer came in, which only hit-tests - Win32 sends a window that appears under a still pointer a move, and a Wayland enter arrives as one.

A click, or a menu the pointer raised, always finds the mouse on. A key other than a modifier finds it off, unless the pointer moved while that key was held down and repeating.

The fades run on the application's animator, reached through the AppContext the form reporting the input hands in, so Input owns nothing that has to be released. The two slots, AnimationSlots::keyboardActive and mouseActive, mirror each other, so a switch from one device to the other is one crossfade. Each step of either fade raises InputSwitchEvent on AppContext::events(), and every visible form repaints whole on it: the colour rules read the two factors as RuleInput::Keyboard and RuleInput::Mouse, and nothing knows which controls of which windows do. The Colour manual says what the rules do with them.

Side Buttons

The two side buttons most mice carry are reported as SideButton::Back and SideButton::Forward - named by what the system takes each to mean, not by where it sits on the mouse:

A side button acts as it goes down, and a second press inside the double-click time is one more press. On Win32 the window answers every side button message itself, so the system raises no WM_APPCOMMAND for the same press.

The form hands the press to the control under the pointer as a SideClickEvent, carrying the button, and walks it up the parents until one stops it. A control answers with an OnSideClick handler, or, where it answers for everything inside it, by overriding nestedSideClick:

// Whatever the pointer stands on inside the browser, a side button is its Back or Forward.
void BrowserControl::nestedSideClick(SideClickEvent& event)
{
    Panel::nestedSideClick(event);   // emits; a handler may stop it
    if (event.propagationStopped())
        return;

    event.stopPropagation();
    const std::ptrdiff_t offset = event.button == SideButton::Back ? -1 : 1;
    travel(offset, historyButton(offset));
}

Reaching the Platform From Below

Some of the framework's own services stand below the context in the module graph - the clipboard in Transfer, the timer hooks in System - and cannot import the module that declares Platform, because Context imports them. They still need the platform: the clipboard wants a listener window on Win32 and the display on Wayland, and a UiTimer wants the timer manager. Two seams serve them, and which one applies depends on whether the service has an object in hand.

The Empty Name and What Stands Behind It

IPlatformServices, declared in ClaFi.Core.System.UiTypes, is a class with a virtual destructor and nothing else. It is the platform as a service below the context can name it, and a service that is handed the platform holds it under this name:

export class Clipboard
{
public:
    explicit Clipboard(IPlatformServices&);
    ...
private:
    IPlatformServices& m_platform;
};

What stands behind the name is each platform layer's own statement, in its own module, and the platform built for the display server derives from it:

The service's platform half - the unit compiled for that platform alone - casts the name to what its platform stands behind it:

// Windows.Transfer.cpp
IMessageWindowFactory& platform = static_cast<IMessageWindowFactory&>(owner.m_platform);
listener = platform.createMessageWindow();

// Wayland.Transfer.cpp
return static_cast<IDisplayAccess&>(owner.m_platform).display();

The cast is sound because a build has one platform: the object behind an IPlatformServices& in a Windows build is a Win32Platform, which derives from IMessageWindowFactory, and there is no other. The cast is also what keeps the neutral name empty. Nothing is declared on IPlatformServices that only one platform can answer, so no platform is made to answer for a thing it has no notion of - Wayland has no message window, and Win32 has no display object - and the neutral module carries no method that half the builds would stub.

The Standing Pointer

A hook has no object in hand. PlatformTimer::start and stop are free functions a UiTimer calls; a DirWatch's platform half is built with nothing but the watch; a Platform static is a static. These reach the platform's object through a pointer that object sets as it is built and clears as it goes:

export class TimerManager
{
public:
    [[nodiscard]] static TimerManager* standing() { return s_standing; }
    ...
private:
    inline static TimerManager* s_standing{ nullptr };
};

// the hook
void start(UiTimer* timer, MilliSeconds delay)
{
    TimerManager* manager = TimerManager::standing();
    if (manager == nullptr)
        unreachable("PlatformTimer: no timer manager stands - a UiTimer outlives the platform");
    ...
}

This is not a singleton. The object is a platform member with a declared place and a declared lifetime; the pointer is a non-owning view of it, and it is null exactly while the platform holds no such object. That null is the whole of the difference: a singleton built on first use would answer a hook called after the platform has gone by building a new manager, silently and at process exit. A standing pointer answers it with unreachable, because the platform stands before anything that owns a timer or a watch and after it - see First Up, Last Down - and a hook finding none standing has found a broken order.

The Platform's Own Objects

What each platform layer builds for its owner, and the two or three rules each carries.

On Win32

WindowsManager is the root of the Windows layer. Its constructor sets the process DPI awareness, opens the OLE apartment the clipboard lives in, and registers the four window classes; its destructor closes the apartment, posts the quit message and unregisters the classes. Every window is handed the manager by whoever makes it - the platform to a FormWindow, the platform to the timer's and the clipboard's message windows - and the manager has no static accessor. The one static state it keeps is the desktop's colour mode as last read, which a broadcast is compared against.

MessageWindow is a message-only HWND on WindowBase alone - no frame, no placement, no alpha, none of what a platform window has. Whoever holds one names itself as its IMessageSink and receives every message the window does, exactly as a Window subclass would without being one; what the sink leaves unhandled goes to the system's default. IMessageSink is also what the manager's window procedure delivers to for every window it made, by the pointer in the window's user data - a Window and a MessageWindow alike.

TimerManager owns a MessageWindow and is its sink for WM_TIMER. It publishes standing() for the two hooks.

On Wayland

DisplayManager is the connection, the bound globals and the event loop. Its constructor connects and throws where it cannot; waitForEvent sleeps on the connection's descriptor, every registered poll source and the appearance bus, and dispatchPending hands every sink what arrived. It publishes standing() for the Platform statics, and nothing else reaches it by name: windows are handed it, and the clipboard casts to IDisplayAccess.

PollSource is a descriptor's place in the loop, held for as long as the object stands: addPollSource in its constructor, removePollSource in its destructor, with the call to make when the descriptor is readable. The platform declares one per manager, after the display and the manager it polls for.

Linux::TimerManager is a thread that waits out the delays and an eventfd it raises; Linux::DirWatchManager is one inotify descriptor. Both live in Platform/Linux because they are the operating system's, not the display server's; both publish standing(); neither knows the loop that polls it.

The Clipboard's Two Halves

Transfer::Clipboard is the worked example of a service that is one object with a neutral half and a platform half. The neutral half - the package this process stands behind, the held reader, the change dispatcher, the generation - is the class's own members, declared in ClaFi.Core.Transfer.Clipboard. The platform half is NativeClipboard: a struct the interface declares without a body and each platform's implementation unit of the same module defines, held through a unique_ptr so the interface names no platform type.

The constructor and destructor of Clipboard are defined in the platform unit, where NativeClipboard is complete. Nothing above the platform layer sees the difference.

Teardown

Construction order is the easy half; the framework's own objects are built by whoever owns them, in the order the owner declares. Teardown is where a design of this shape earns its keep, because the things going down still reach for the platform, and the platform has to be there.

What Stays Static, and Why

The rule is not "no statics"; it is that no static holds anything that must be released in an order. A timer, a handle, a thread, a protocol object, a listener on something else - each of those has an owner with a declared place. What remains static holds none of them:

Adding a Platform Service

The questions to answer, in order:

1. Who owns it? A service the platform layer makes from the operating system - a window, a descriptor, an apartment - belongs to the platform. A service the application runs for itself - the animations - belongs to AppContext. Nothing belongs to a namespace.
2. Where in the list? After everything it is made from, before everything that is made from it. On Wayland, a descriptor the loop must poll gets a PollSource declared after both the display and the service.
3. Who reaches it, and from where? Code above the context: give the context an accessor, as clipboard() and animator(). A service below the context that is handed the platform once: add a method to the platform layer's IPlatformServices derivative - IMessageWindowFactory or IDisplayAccess - never to the neutral name. A hook with no object in hand: a standing() pointer on the service, set and cleared by the service, unreachable when null.
4. Where do the bodies go? A class member is defined in the module that declared its class, so a platform-neutral interface with platform bodies gets one implementation unit per platform of the same module - Windows.Transfer.cpp and Wayland.Transfer.cpp are both module ClaFi.Core.Transfer.Clipboard;. Its platform state goes behind a struct the interface declares and the platform unit defines, held through a unique_ptr.
5. What does it do on the way out? Its destructor, and only that. If it must act while a later platform member still stands, the order is wrong; move it.

Reference

The platform's neutral half, ClaFi.Core.Context.FormContext:

The two platforms and their facades:

The seams:

What the context hands out:

What the platform reports, as the framework holds it: