Safe Haskell	None
Language	GHC2021

Wireform.Transport.Receive

Description

Receive-side magic-ring transport.

The parser consumes bytes from a ReceiveTransport. The producer (a network recv loop, a TLS context, an io_uring backend, an in-memory test fixture, …) writes into the magic ring at head and the parser drains [tail, head).

Cursor model

Word64 positions are monotonic (never wrap during process lifetime). The byte at logical position p lives at ringBase + (p .&. ringMask) in the ring.

Why the ring is stored as three primitive fields

ReceiveTransport embeds the ring's base pointer, size, and mask directly rather than carrying a MagicRing. That keeps the type free of the ring's phantom s parameter, so the rank-2 scope safety of withMagicRing is something callers opt into at the slice layer rather than something that ripples through every ReceiveTransport-using package. receiveRing reconstructs a polymorphic MagicRing for callers that still want to call ringBase ringSize ringMask on a record value.

Synopsis

data ReceiveTransport = ReceiveTransport {
- receiveRingBase :: !(Ptr Word8)
- receiveRingSize :: !Int
- receiveRingMask :: !Int
- receiveLoadHead :: !(IO Word64)
- receiveAdvanceTail :: !(Word64 -> IO ())
- receiveWaitData :: !(Word64 -> IO ReceiveWait)
- receiveClose :: !(IO ())
}
data ReceiveWait
- = ReceiveMoreData !Word64
- | ReceiveEndOfInput
- | ReceiveFailed !SomeException
receiveRing :: forall {k} (s :: k). ReceiveTransport -> MagicRing s

Documentation

data ReceiveTransport Source #

A producer-side cursor + a slot to wait on more data.

The parser interacts with data exclusively through this record. Implementations bind one to a socket, TLS context, io_uring instance, or an in-memory fixture.

Constructors

ReceiveTransport

Fields

receiveRingBase :: !(Ptr Word8)
Base address of the ring's first mapping.
receiveRingSize :: !Int
Physical ring size (N, not 2N). Always a power of two.
receiveRingMask :: !Int
ringSize - 1, cached for cheap pos .&. mask.
receiveLoadHead :: !(IO Word64)
Read the producer's current head position (monotonically increasing).
receiveAdvanceTail :: !(Word64 -> IO ())
Consumer publishes a new tail position (monotonically increasing). The transport may use this for backpressure or buffer reuse.
receiveWaitData :: !(Word64 -> IO ReceiveWait)
Block until head advances past the given position. Parks on the IO manager when blocking (same thread as the parser).
receiveClose :: !(IO ())
Release resources. Idempotent.

data ReceiveWait Source #

Outcome of waiting for more data.

Constructors

ReceiveMoreData !Word64	New head position.
ReceiveEndOfInput	Clean end (sticky: once returned, all subsequent calls return this).
ReceiveFailed !SomeException	Producer-side failure (sticky).

Instances

Instances details

Show ReceiveWait Source #
Instance details Defined in Wireform.Transport.Receive Methods showsPrec :: Int -> ReceiveWait -> ShowS # show :: ReceiveWait -> String # showList :: [ReceiveWait] -> ShowS #

receiveRing :: forall {k} (s :: k). ReceiveTransport -> MagicRing s Source #

Reconstruct the underlying MagicRing. Polymorphic in the phantom s: the resulting handle does not inherit the scope of whatever ring originally produced these bytes, so callers should treat it as un-scoped (i.e. equivalent to the pre-MagicRing s world). Use withMagicRing directly when you need the type-system-enforced safety.