Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Channel.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include <PhosphorChannel/phosphorchannel_export.h>
7
8#include <cstddef>
9#include <cstdint>
10#include <string>
11#include <string_view>
12
13// PhosphorChannel moves frames of opaque bytes from one process to another,
14// in order and with backpressure. A channel is unidirectional: one writer
15// feeds one reader. Each channel has a codec tag that names the format of its
16// payload; the library stores the tag and never reads the payload.
17//
18// Two transports:
19// - the shared-memory ring (Ring.h, handed over by Handshake.h), between two
20// processes on one computer, with no system call per frame while the
21// reader keeps up;
22// - the stream (Stream.h): several channels over any connected byte stream,
23// such as a Unix socket or the standard input and output of an ssh
24// process, each channel with its own flow control.
25//
26// No Qt and no other Phosphor library: a headless daemon links it alone.
27// Linux only.
28
29namespace PhosphorChannel {
30
34inline constexpr std::uint32_t ProtocolVersion = 1;
35
37inline constexpr std::size_t MaxCodecBytes = 64;
38
41PHOSPHORCHANNEL_EXPORT bool validCodec(std::string_view codec);
42
55
67
69PHOSPHORCHANNEL_EXPORT std::string versionMismatch(std::uint32_t theirs);
70
71} // namespace PhosphorChannel
Definition Channel.h:29
constexpr std::uint32_t ProtocolVersion
Covers the handshakes, the stream's packets and the ring's layout.
Definition Channel.h:34
WriteResult
Definition Channel.h:43
@ Closed
No frame can go any more: the reader closed the channel, the other process went away,...
Definition Channel.h:53
@ Written
Definition Channel.h:44
@ TooLarge
The frame can never fit this channel.
Definition Channel.h:50
@ WouldBlock
The channel is full.
Definition Channel.h:48
ReadResult
Definition Channel.h:56
@ Frame
Definition Channel.h:57
@ Corrupt
The other process broke the protocol, so nothing after it can be trusted.
Definition Channel.h:65
@ Empty
No frame waits now. Wait until the transport says that one came.
Definition Channel.h:59
PHOSPHORCHANNEL_EXPORT std::string versionMismatch(std::uint32_t theirs)
The message for two protocol versions that do not match.
PHOSPHORCHANNEL_EXPORT bool validCodec(std::string_view codec)
1 to MaxCodecBytes of printable ASCII without spaces, such as "afterglow.state.v1".
constexpr std::size_t MaxCodecBytes
The longest codec tag, in bytes.
Definition Channel.h:37