From 1a79cb6c4d180faea3fd4a24d5ff393a17d54439 Mon Sep 17 00:00:00 2001 From: Taylan Kammer Date: Fri, 29 May 2026 17:42:22 +0200 Subject: docs/c1/1-parse.md: Add buffering section. --- docs/c1/1-parse.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/c1/1-parse.md b/docs/c1/1-parse.md index f6d677a..31e340a 100644 --- a/docs/c1/1-parse.md +++ b/docs/c1/1-parse.md @@ -131,6 +131,21 @@ next file header appears. (The header data need to be terminated with a blank ASCII character such as a newline. The reason why the closing parenthesis does not act as a terminator unto itself will become apparent later.) +#### Buffering + +To enable the aforementioned stream parsing strategy, the parser does not use +automatic buffering. If it did, it might inadvertently consume some bytes +beyond the currently parsed datum, leaving the stream inconsistent. + +The parser could provide access to its buffer, such that one could access the +unused bytes, but it's simpler and more flexible to let buffering be handled +externally from the parser. + +In other words: If the parser is meant to be used on an I/O stream connected to +expensive system calls, such as a file handle or network socket, it's best to +wrap that stream in some intermediate object which asks the system for large +chunks of data at once, and stores the data in a buffer. + ### Datum labels -- cgit v1.2.3