Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IpcEngine.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
5#include <PhosphorIpc/phosphoripc_export.h>
6
7#include <QtCore/qtmetamacros.h> // QT_BEGIN_NAMESPACE / QT_END_NAMESPACE
8
9QT_BEGIN_NAMESPACE
10class QQmlEngine;
11QT_END_NAMESPACE
12
13namespace PhosphorIpc {
14
15class IpcRouter;
16
17// Bridge between the application's IpcRouter (constructed in main())
18// and QML-side IpcTarget instances (instantiated by the engine).
19// The router is stored as a dynamic property on the engine
20// ("phosphorIpcRouter"); IpcTarget::componentComplete() reads it
21// back via qmlEngine(this)->property(...).
22//
23// Why a free function rather than a QML singleton or context
24// property: the router's lifetime is owned by main(), not the
25// engine, so QML_SINGLETON's lazy per-engine construction model
26// doesn't fit. setContextProperty would work but pollutes the QML
27// root namespace; an opaque engine dynamic property keeps the
28// integration invisible to surface QML.
29//
30// Idempotent: calling install() twice with the same router is a
31// no-op; calling with a different router on the same engine logs
32// a qWarning and replaces the binding (test-environment use case).
33//
34// Thread affinity: install(), uninstall(), and routerFor() must be
35// called on the engine's owning thread (the GUI thread in typical
36// usage). QQmlEngine is thread-affine, and the bookkeeping globals
37// inside ipcengine.cpp are not synchronised; an off-thread call is
38// asserted against in debug builds.
39namespace IpcEngine {
40
41PHOSPHORIPC_EXPORT void install(QQmlEngine* engine, IpcRouter* router);
42
43// Inverse of install(). Clears the engine's router property.
44// Called from main() during shutdown if the application wants to
45// drop the binding before the engine is destroyed (the typical
46// reverse-order destruction handles it implicitly).
47PHOSPHORIPC_EXPORT void uninstall(QQmlEngine* engine);
48
49// Resolve the router previously installed on this engine. Returns
50// nullptr if no install() has been called for this engine.
51[[nodiscard]] PHOSPHORIPC_EXPORT IpcRouter* routerFor(QQmlEngine* engine);
52
53} // namespace IpcEngine
54
55} // namespace PhosphorIpc
Definition IpcRouter.h:89
Definition IpcEngine.h:39
PHOSPHORIPC_EXPORT IpcRouter * routerFor(QQmlEngine *engine)
PHOSPHORIPC_EXPORT void install(QQmlEngine *engine, IpcRouter *router)
PHOSPHORIPC_EXPORT void uninstall(QQmlEngine *engine)
Definition IpcCallContext.h:10