// MobileGL - MobileGL/MG_Remote/Transport/EventRing.h // Copyright (c) 2025-2026 MobileGL-Dev // Licensed under the GNU Lesser General Public License v3.0: // https://www.gnu.org/licenses/gpl-3.0.txt // https://www.gnu.org/licenses/lgpl-3.0.txt // SPDX-License-Identifier: LGPL-3.0-only // End of Source File Header // SEG_EVENT: the server -> client reverse channel. Owner: package s1. // // WHAT P5 OWES HERE AND NOTHING MORE (BRIEF R-12, and s1's brief): it must be // able to CARRY OnBufferWriteback, OnGpuWritten and OnSurfaceChanged. The other // seven MGPipeCallbacks members are off P5's reduced path, and THE OVERFLOW // POLICY IS P9's - what is here is the mechanism (a full ring latches // eventRingFull, a lossy post that is dropped counts in eventDropped) and not a // policy that decides between them. // // IT IS A SECOND RingControl, NOT A THIRD CURSOR SET. RingControl carries two // cursor triples (SEG_CMD and SEG_STAGE) and adding a third would resize the // shared page that Ring.h static_asserts at exactly 4096 bytes. So SEG_EVENT // gets its OWN control page at its own head and drives it with the Cmd cursor // set - the same RingProducer/RingConsumer code, in the opposite direction. The // two EVENT FLAGS still live in the SEG_CMD page, because that is where Ring.h // declares them and where the client's own waits already look. // // THE PAYLOAD SHAPES ARE FIXED-WIDTH AND LIVE HERE, not in MG_Pipe's headers. // Nothing under Transport/ may reach MobileGL/Includes.h (WireLog.h:9-24, and // the purity gate's `wire-header` probe), so MGPipeHandle / MGPRange / // MGPSurfaceInfo cannot be named in this file. The wire shapes below mirror them // field for field and the SESSIONS assert the two agree, which is the same // discipline the rest of the wire is held to: a wire struct is fixed-width, and // the conversion happens where the frontend types are legal. #pragma once #include "Doorbell.h" #include "Ring.h" #include #include namespace MobileGL::MG_Remote::Transport { // Record kinds on SEG_EVENT. 0 is kRingPadRecordKind and can never be an // event, which is why the list starts at 1. APPEND-ONLY, for the same reason // the opcode space is (CONTRACT-P5C §7.7): kEventGlError is the first addition. enum EventKind : std::uint16_t { kEventNone = 0, kEventBufferWriteback = 1, // MGPipeCallbacks::OnBufferWriteback kEventGpuWritten = 2, // MGPipeCallbacks::OnGpuWritten kEventSurfaceChanged = 3, // MGPipeCallbacks::OnSurfaceChanged kEventGlError = 4, // PipeInputs::RecordError, posted by the server session }; // The 8-byte {slot, gen} pair, mirrored (MGPipeHandles.h:54-65). struct EventHandle { std::uint32_t Slot; std::uint32_t Gen; }; static_assert(sizeof(EventHandle) == 8, "the handle is the 8-byte {slot, gen} pair"); // MGPRange, mirrored (MGPipeTypes.h:63-67). struct EventRange { std::uint64_t Offset; std::uint64_t Size; }; static_assert(sizeof(EventRange) == 16, "MGPRange is 16 bytes on the wire"); // OnBufferWriteback(res, offset, MGPBlobRef bytes). The bytes follow this // head INSIDE THE RECORD: the blobref the client hands the frontend names // SEG_EVENT and the in-segment offset of those inline bytes, which is what // makes "the destination is the client's shadow" (contract table 1 row 22) // reachable without a second segment. `Size` is therefore the record's own // tail length and is cross-checked against it. struct EventBufferWritebackHead { EventHandle Resource; std::uint64_t Offset; // destination offset inside the resource std::uint64_t Size; // inline byte count that follows }; static_assert(sizeof(EventBufferWritebackHead) == 24, "wire shape"); // OnGpuWritten(res, rangeCount, ranges). EventRange[RangeCount] follows. struct EventGpuWrittenHead { EventHandle Resource; std::uint32_t RangeCount; std::uint32_t Pad0; }; static_assert(sizeof(EventGpuWrittenHead) == 16, "wire shape"); // OnSurfaceChanged(const MGPSurfaceInfo*), mirrored (MGPipeTypes.h:1394-1401). struct EventSurfaceChangedHead { std::uint32_t Width; std::uint32_t Height; std::uint32_t InternalFormat; std::uint16_t Samples; std::uint16_t Layers; std::uint8_t IsDefault; std::uint8_t Pad0[7]; }; static_assert(sizeof(EventSurfaceChangedHead) == 24, "MGPSurfaceInfo is 24 bytes on the wire"); // PipeInputs::RecordError(code, info) (CONTRACT-P5C §1). The NUL-terminated // message follows this head INSIDE THE RECORD: MessageBytes = strlen + 1 and // the NUL travels, so MessageBytes == 0 is the corrupt shape, never "no // message". A longer message is TRUNCATED AT THE PRODUCER to the cap; the cap // is a static_assert here, not a runtime check, because it is part of the // wire's shape rather than a policy a peer may disagree about. struct EventGlErrorHead { std::uint32_t Code; // the frontend ErrorCode, widened std::uint32_t MessageBytes; // strlen + 1, the NUL included }; static_assert(sizeof(EventGlErrorHead) == 8, "wire shape"); inline constexpr std::uint32_t kEventGlErrorMaxMessageBytes = 1024; static_assert(kEventGlErrorMaxMessageBytes == 1024, "CONTRACT-P5C §1 caps an inline GL-error message at 1024 bytes, NUL included"); // The server's end. One producer: the apply thread, by construction. class EventRingProducer { public: EventRingProducer() = default; // `eventControl` is SEG_EVENT's own control page; `cmdControl` is the // SEG_CMD page, because Ring.h declares eventRingFull / eventDropped // there and the client's waits already look at it. EventRingProducer(RingControl* eventControl, RingControl* cmdControl, void* base, std::uint64_t capacityBytes) : m_cmdControl(cmdControl), m_producer(eventControl, base, capacityBytes, RingCursorSet::Cmd) {} bool Valid() const { return m_producer.Valid() && m_cmdControl != nullptr; } // Reserves one event record. nullptr means the ring is full: the caller // decides, and the two flags are how it says which decision it took. // THIS FUNCTION DOES NOT DECIDE - that is P9's. void* Reserve(EventKind kind, std::uint64_t payloadBytes) { void* slot = m_producer.Reserve(static_cast(kind), kRecNone, payloadBytes); if (slot == nullptr && m_cmdControl != nullptr) { // "SEG_EVENT full, server stopped applying" - Ring.h:123. Latched // here, cleared by the consumer once it has drained. m_cmdControl->eventRingFull.store(1, std::memory_order_release); } return slot; } // For a LOSSY event the caller could not place. Lossless events must // never call this; they wait for the client to drain instead. void CountDrop() { if (m_cmdControl != nullptr) { m_cmdControl->eventDropped.fetch_add(1, std::memory_order_relaxed); } } // Publish, THEN ring - the same order as the forward direction, and for // the same reason (NotifyIfParked's PRECONDITION: the fence only orders what // precedes it, so ringing first reopens the lost-wakeup window). void PublishAndNotify(Doorbell& clientBell, std::atomic& producerParked) { m_producer.Publish(); NotifyIfParked(clientBell, producerParked); } RingProducer& Ring() { return m_producer; } private: RingControl* m_cmdControl = nullptr; RingProducer m_producer; }; // The client's end. One consumer: the GL thread, which drains between verbs. class EventRingConsumer { public: EventRingConsumer() = default; EventRingConsumer(RingControl* eventControl, RingControl* cmdControl, void* base, std::uint64_t capacityBytes, const void* segmentBase) : m_cmdControl(cmdControl), m_consumer(eventControl, base, capacityBytes, RingCursorSet::Cmd), m_segmentBase(static_cast(segmentBase)) {} bool Valid() const { return m_consumer.Valid() && m_cmdControl != nullptr; } bool Pop(RingRecordView& out, bool* outCorrupt = nullptr) { return m_consumer.Pop(out, outCorrupt); } // Release the bytes and clear the full latch. Only after the caller has // finished with every payload pointer it popped: a writeback's bytes live // in the ring itself, so retiring early is the R-11 violation one level // down. void SetLink(ILink* link) { m_link = link; } void Drained() { m_consumer.PublishRetired(); if (m_cmdControl != nullptr) { // P5e (ra, CONTRACT-P5E §2.6): CLEARING THE LATCH IS ONLY HALF OF IT. Under // flow control the server is PARKED on this flag - either inside a producer // that could not Reserve, or at a record boundary refusing to start the next // record - and a cleared flag with no bell is a wakeup lost exactly the way // the forward direction's publish-then-ring order exists to prevent. The // exchange is what makes the ring one-shot: only the drain that actually found // the flag up rings, so a steady stream of drains costs one relaxed RMW. const bool wasFull = m_cmdControl->eventRingFull.exchange(0, std::memory_order_acq_rel) != 0; if (wasFull && m_serverBell != nullptr) { NotifyIfParked(*m_serverBell, m_cmdControl->consumerParked); } } if (m_link) m_link->Flush(); } // The bell the SERVER parks on, lent by the session so that Drained() can ring it. // Null in every fixture that consumes a ring without a server behind it, and the // ring's clear then behaves exactly as it did before P5e. void SetServerDoorbell(Doorbell* bell) { m_serverBell = bell; } // Byte offset of `payload` inside SEG_EVENT, which is what an // OnBufferWriteback MGPBlobRef must carry (Seg = kSegEvent, Offset = // this, Size = the head's Size). Never a host address - R-2's rule B. std::uint64_t OffsetInSegment(const void* payload) const { return static_cast(static_cast(payload) - m_segmentBase); } std::uint64_t DroppedEvents() const { return m_cmdControl == nullptr ? 0 : m_cmdControl->eventDropped.load(std::memory_order_relaxed); } bool RingIsFull() const { return m_cmdControl != nullptr && m_cmdControl->eventRingFull.load(std::memory_order_acquire) != 0; } RingConsumer& Ring() { return m_consumer; } private: RingControl* m_cmdControl = nullptr; ILink* m_link = nullptr; RingConsumer m_consumer; const std::uint8_t* m_segmentBase = nullptr; // P5e (ra): the server's bell, rung by Drained() when it cleared a full latch. Doorbell* m_serverBell = nullptr; }; } // namespace MobileGL::MG_Remote::Transport