Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IpcPendingReply.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 <QJsonValue>
8#include <QPointer>
9#include <QString>
10
11namespace PhosphorIpc {
12
13class IpcRouter;
14
15// The answer to a wire call that a target gives later, after its method
16// returned. IpcCallContext::deferReply() makes one inside the method, before
17// the work starts, so that work that ends at once can answer through it:
18//
19// Q_INVOKABLE void install(const QString& package)
20// {
21// // std::list: a job stays where it is while others come and go.
22// Job& job = m_jobs.emplace_back();
23// job.reply = deferReply();
24// startInstall(job, package); // answers through job.reply when it ends
25// }
26//
27// Keep one pending reply per call. A single member that every call
28// assigns to abandons the call it held when the next call comes.
29//
30// The router sends no reply when such a method returns, and the method's
31// return value is dropped. The client gets at most one answer for the call:
32// the first of finish(), fail(), the CALL_ABANDONED error this object sends
33// when it is destroyed or overwritten unanswered, and the error of an
34// IpcCallContext::sendErrorReply the method made before it returned. A
35// connection that closes first gets none. Replies to the connection's other
36// calls go out meanwhile, as their methods return, so a deferred reply may
37// arrive after replies to calls made later. Every reply carries the
38// request's id, and a client that has more than one call in flight on a
39// connection must give each its own id, one that no live subscription on
40// the connection uses either (the error that ends a subscription carries
41// the subscription id). A call sent without an id has id 0: finish() then
42// answers with "id":0, and fail() with an error that carries no id, like
43// any error for a request without one.
44//
45// Everything the router writes to one connection goes out in the order it
46// was written: an event sent with IpcRouter::sendEvent before finish() reaches
47// the client before the reply.
48//
49// A pending reply for a connection that has closed is still valid: finish()
50// and fail() drop the answer and return false, without a warning. The same
51// holds after the router has been destroyed.
52//
53// Move-only. Use it on the router's thread only, including its destruction:
54// it writes to the connection directly. Debug builds assert this. Release
55// builds warn, and finish() and fail() return false and keep the call, which
56// the object can still answer on the router's thread. A call that is never
57// answered there (the object is destroyed off the thread too) waits until
58// its connection closes, and holds one of the connection's
59// IpcRouter::MaxPendingCallsPerConnection places meanwhile.
60class PHOSPHORIPC_EXPORT IpcPendingReply
61{
62public:
63 // Holds no call. finish() and fail() do nothing and return false.
65 // An unanswered call fails with CALL_ABANDONED, so the client does not
66 // wait for an answer that never comes.
69 // Abandons the call this object held, as the destructor does, then takes
70 // over the call of `other`.
74
75 // True while the object holds a call: from deferReply() until finish(),
76 // fail() or a move away. False for a default-constructed object and for
77 // every deferral that holds no call (IpcCallContext::deferReply lists
78 // them: outside a call, a second deferral, a call from no connection,
79 // past IpcRouter::MaxPendingCallsPerConnection). It does not say that the call can still be
80 // answered: the connection may have closed, or the method may have
81 // failed the call with sendErrorReply, and finish() then returns false.
82 [[nodiscard]] bool isValid() const;
83
84 // The connection that made the call, as IpcCallContext::connectionId()
85 // reported it, also after the call was answered: the id to send the
86 // call's events to (IpcRouter::sendEvent). 0 for an object that never
87 // held a call and for a moved-from one.
88 [[nodiscard]] quint64 connectionId() const;
89
90 // Sends {"type":"reply","id":<request id>,"result":<result>}. An
91 // undefined result goes out as null. Returns true when the reply was
92 // queued on an open connection, false when there was nothing to answer
93 // (already answered, no call), when the connection has closed, and off
94 // the router's thread. A client that went away before the router
95 // noticed loses a reply that returned true.
96 bool finish(const QJsonValue& result = QJsonValue());
97
98 // Sends {"type":"error","id":<request id>,"code":"CALL_FAILED",
99 // "message":<message>}, the error IpcCallContext::sendErrorReply sends.
100 // Returns as finish() does.
101 bool fail(const QString& message);
102
103 // Sends an error with the target's own `code`, for a failure a client is
104 // meant to tell apart from others. An empty code sends CALL_FAILED. The
105 // code goes out as given: pick one outside IpcProtocol's ErrorCode list,
106 // whose codes name what the router found, so that a client can tell the
107 // router's errors from the target's. Returns as finish() does.
108 bool fail(const QString& code, const QString& message);
109
110private:
111 friend class IpcRouter;
112 IpcPendingReply(IpcRouter* router, quint64 token, quint64 connectionId);
113
114 // Answers the call with CALL_ABANDONED when this object still holds it.
115 void abandon();
116 // Gives up the call for answering: its token, or 0 when there is
117 // nothing to answer here (no call, router gone, wrong thread).
118 [[nodiscard]] quint64 takeToken();
119
120 QPointer<IpcRouter> m_router;
121 // The router's key for the call. 0 when this object holds none.
122 quint64 m_token = 0;
123 quint64 m_connectionId = 0;
124};
125
126} // namespace PhosphorIpc
IpcPendingReply & operator=(const IpcPendingReply &)=delete
bool fail(const QString &message)
quint64 connectionId() const
friend class IpcRouter
Definition IpcPendingReply.h:111
IpcPendingReply(IpcPendingReply &&other) noexcept
bool fail(const QString &code, const QString &message)
IpcPendingReply(const IpcPendingReply &)=delete
IpcPendingReply & operator=(IpcPendingReply &&other) noexcept
bool finish(const QJsonValue &result=QJsonValue())
Definition IpcRouter.h:89
Definition IpcCallContext.h:10