lib/acp/src/reader/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! A reader splits a stream of bytes into lines at each newline, inside one buffer whose size the
 2 //! caller fixes in advance. The package's client reads the agent's output through it, and any
 3 //! program that reads newline-separated messages from a pipe can use it alone.
 4 //!
 5 //! Memory for input from another program has to stay bounded, and its size has to be known before
 6 //! that program starts.
 7 //!
 8 //! A line can arrive in pieces, one read can hold more than one line, the last line can lack its
 9 //! newline, and a line can be longer than any buffer set aside for it.
10 //!
11 //! The buffer holds the longest allowed line plus its newline, and `Storage.init` allocates it in
12 //! one allocation. After `activate`, nothing the reader does allocates: the caller reads input into
13 //! free space the reader hands out, and the reader returns each line as a slice of its buffer.
14 //! Before it hands out free space, the reader moves the unread bytes to the front of the buffer
15 //! (*compaction*), and a line returned earlier stops being valid then. A line longer than the limit
16 //! stops the reader for good (*terminal*), before any caller parses it, and every later poll fails
17 //! with `error.ReaderMessageCapacityExceeded`. The reader keeps counters a caller can read for the
18 //! lines rejected and the bytes waiting, and a caller reads the longest line seen (*high-water
19 //! mark*). The reader states the buffer's size formula and what the buffer leaves out in a
20 //! compile-time record (*capacity claim*), and that record names a test for each promise it makes.
21 //! `default_limits` sets the line limit to 2 MiB for callers with no size of their own.
22 const capacity = @import("capacity.zig");
23 const storage = @import("storage.zig");
24 
25 /// A line limit of 2 MiB (2 * 1024 * 1024 bytes) for callers with no size of their own. The package
26 /// exports it as `acp.default_reader_limits`, and the README's example passes it to the client.
27 pub const default_limits: Limits = .{ .message_bytes = 2 * 1024 * 1024 };
28 
29 pub const Capacity = capacity.Capacity;
30 pub const Exhaustion = storage.Exhaustion;
31 pub const Limits = capacity.Limits;
32 pub const Poll = storage.Poll;
33 pub const Status = storage.Status;
34 pub const Storage = storage.Storage;