Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Ring.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
7#include <PhosphorChannel/phosphorchannel_export.h>
8
9#include <cstddef>
10#include <cstdint>
11#include <memory>
12#include <string>
13#include <string_view>
14
15#include <sys/types.h>
16
17// The shared-memory ring: a memfd that both processes map, sealed so that its
18// size can never change (F_SEAL_SHRINK, F_SEAL_GROW, F_SEAL_SEAL). It cannot
19// be sealed against writes, because both ends write their positions. The
20// write position, the read position and each end's wake request sit on cache
21// lines of their own, and the two closed flags share one. The writer writes
22// whole frames, and a skip record pads the wrap.
23//
24// A connected pair of Unix sockets wakes the ends, one socket in each
25// process: the writer sends a byte when it wrote to a reader that waits, and
26// the reader sends one when it freed the space that a waiting writer asked
27// for. While frames wait, neither end makes a system call. Each process holds
28// only its own socket, so neither can change how the other's blocks. When
29// the other process exits, its socket closes: the wake fd becomes readable.
30// Once an end drains it (clearSpaceSignal(), clearDataSignal(), or the wait
31// in write()) or fails to signal, its writes say Closed, and its reads say
32// Closed after the last frame.
33//
34// The other process can change the shared memory at any time. The reader
35// checks each position and length that it reads, copies each frame out
36// before it returns it, and reports ReadResult::Corrupt for a ring that
37// breaks the layout.
38//
39// A ring belongs to the process that made or accepted it. After fork() the
40// child must exec or _exit: its copy of the object leaves the ring alone
41// when it is destroyed, but it must not read or write.
42
43namespace PhosphorChannel {
44
45class RingWriter;
46PHOSPHORCHANNEL_EXPORT bool offerRing(int socket, RingWriter& ring, int timeoutMs, std::string* error);
47
48class PHOSPHORCHANNEL_EXPORT RingWriter
49{
50public:
52 static constexpr std::size_t MinCapacity = 4096;
53 static constexpr std::size_t MaxCapacity = std::size_t(1) << 30;
54
57 static std::unique_ptr<RingWriter> create(std::size_t capacity, std::string codec, std::string* error);
59 RingWriter(const RingWriter&) = delete;
60 RingWriter& operator=(const RingWriter&) = delete;
61
64 WriteResult tryWrite(std::string_view frame);
67 WriteResult write(std::string_view frame, int timeoutMs);
69 std::size_t maxFrame() const;
70 std::size_t capacity() const
71 {
72 return m_capacity;
73 }
74 const std::string& codec() const
75 {
76 return m_codec;
77 }
78
83 int spaceFd() const
84 {
85 return m_wakeFd;
86 }
88
91 void close();
92
95 int memoryFd() const
96 {
97 return m_memoryFd;
98 }
99
100private:
101 friend bool offerRing(int socket, RingWriter& ring, int timeoutMs, std::string* error);
102 RingWriter() = default;
103 bool fits(std::uint64_t readPos, std::size_t bytes) const;
105 void handedOver();
106
107 int m_memoryFd = -1;
108 int m_wakeFd = -1;
109 int m_peerWakeFd = -1;
110 void* m_map = nullptr;
111 std::size_t m_mapSize = 0;
112 std::size_t m_capacity = 0;
113 std::uint64_t m_writePos = 0;
114 std::uint64_t m_readPosSeen = 0;
115 pid_t m_owner = 0;
116 bool m_closed = false;
117 bool m_broken = false;
118 bool m_offered = false;
119 std::string m_codec;
120};
121
122class PHOSPHORCHANNEL_EXPORT RingReader
123{
124public:
130 static std::unique_ptr<RingReader> attach(int memoryFd, int wakeFd, std::string codec, std::size_t maxCapacity,
131 std::string* error);
133 RingReader(const RingReader&) = delete;
134 RingReader& operator=(const RingReader&) = delete;
135
139 ReadResult read(std::string& frame);
140 const std::string& codec() const
141 {
142 return m_codec;
143 }
144 std::size_t capacity() const
145 {
146 return m_capacity;
147 }
148
154 int dataFd() const
155 {
156 return m_wakeFd;
157 }
159
162 void close();
163
164private:
165 RingReader() = default;
166
167 int m_memoryFd = -1;
168 int m_wakeFd = -1;
169 void* m_map = nullptr;
170 std::size_t m_mapSize = 0;
171 std::size_t m_capacity = 0;
172 std::uint64_t m_readPos = 0;
173 std::uint64_t m_writePosSeen = 0;
174 pid_t m_owner = 0;
175 bool m_corrupt = false;
176 bool m_closed = false;
177 bool m_writerGone = false;
178 std::string m_codec;
179};
180
181} // namespace PhosphorChannel
int dataFd() const
Readable when the writer wrote after a read() returned Empty, closed the ring, or went away.
Definition Ring.h:154
static std::unique_ptr< RingReader > attach(int memoryFd, int wakeFd, std::string codec, std::size_t maxCapacity, std::string *error)
Maps the ring of a writer.
std::size_t capacity() const
Definition Ring.h:144
const std::string & codec() const
Definition Ring.h:140
void close()
Tells the writer that nothing reads any more: its writes return Closed.
RingReader & operator=(const RingReader &)=delete
RingReader(const RingReader &)=delete
ReadResult read(std::string &frame)
The next frame in frame, without waiting.
Definition Ring.h:49
int spaceFd() const
Readable when the reader freed the space that a WouldBlock asked for, closed the ring,...
Definition Ring.h:83
static constexpr std::size_t MaxCapacity
Definition Ring.h:53
WriteResult tryWrite(std::string_view frame)
Writes one frame without waiting.
std::size_t maxFrame() const
The largest frame that the ring takes.
friend bool offerRing(int socket, RingWriter &ring, int timeoutMs, std::string *error)
Sends ring over socket and waits for the answer.
int memoryFd() const
The memfd of the ring.
Definition Ring.h:95
RingWriter(const RingWriter &)=delete
const std::string & codec() const
Definition Ring.h:74
std::size_t capacity() const
Definition Ring.h:70
void close()
Tells the reader that no frame follows.
WriteResult write(std::string_view frame, int timeoutMs)
Waits up to timeoutMs (-1: no limit) for space.
RingWriter & operator=(const RingWriter &)=delete
static std::unique_ptr< RingWriter > create(std::size_t capacity, std::string codec, std::string *error)
A ring of capacity bytes (rounded up to 8) for codec.
static constexpr std::size_t MinCapacity
The smallest and the largest data area, in bytes.
Definition Ring.h:52
Definition Channel.h:29
WriteResult
Definition Channel.h:43
ReadResult
Definition Channel.h:56
PHOSPHORCHANNEL_EXPORT bool offerRing(int socket, RingWriter &ring, int timeoutMs, std::string *error)
Sends ring over socket and waits for the answer.