streamio

nimony/lib/std/streamio.nim

• type TlsEngine = ref TlsEngine.Obj not nil
• type TlsEngine.Obj = object
• type Adapter = ref Adapter.Obj not nil
• type Adapter.Obj = object
• method start(e: ref TlsEngine.Obj not nil; host: string)

  Begin the handshake for host (queues the first flight).

• method recordsIn(e: ref TlsEngine.Obj not nil; src: openArray[char]; used: var int64)

  Bytes from the network. Reports how many were taken.

• method recordsOut(e: ref TlsEngine.Obj not nil; dest: var string)

  Appends whatever must go to the network now.

• method appIn(e: ref TlsEngine.Obj not nil; src: openArray[char]; used: var int64)

  Plaintext to send; its records come out of recordsOut.

• method appOut(e: ref TlsEngine.Obj not nil; dest: var string)

  Appends the plaintext received so far.

• method close(e: ref TlsEngine.Obj not nil)

  Queue close_notify.

• method isConnected(e: ref TlsEngine.Obj not nil): bool

  The handshake has completed and application data may flow.

• method isPeerClosed(e: ref TlsEngine.Obj not nil): bool

  The peer sent close_notify: what appOut has handed out is all of it.

• method run(a: ref Adapter.Obj not nil; src: openArray[char]; used: var int64; dest: var string; final: bool)

  Transform a prefix of src, append the output to dest and report in used how many bytes of src were taken. final means no more input will follow: write the trailer, or check that the stream really ended.

• method attach(a: ref Adapter.Obj not nil; reading: bool)

  Called by setAdapter with the direction the adapter now serves. An adapter that only works one way raises for the other.

• method hasMore(a: ref Adapter.Obj not nil): bool

  False for a read adapter whose stream has ended on its own — an HTTP body after Content-Length bytes or the last chunk — although the source has not. The reader then returns 0, and the bytes below stay where they are.

• func dollar`.CoreKind(e: CoreKind): string

• type Reader = object
    core: ref CoreObj
    buf: string
    pos: int64
    raw: string
    adapter: ref Adapter.Obj
    eof: bool
    step: int64

• type Writer = object
    core: ref CoreObj
    buf: string
    adapter: ref Adapter.Obj
    finished: bool

• proc =destroy(r: Reader)
• proc =wasMoved(r: var Reader)
• proc =dup(x: Reader): Reader
• proc =copy(dest: var Reader; src: Reader)
• proc =destroy(w: Writer)
• proc =wasMoved(w: var Writer)
• proc =dup(x: Writer): Writer
• proc =copy(dest: var Writer; src: Writer)
• proc deadline(r: Reader): Deadline

  The standing deadline for I/O on the underlying descriptor. Bytes already buffered and in-memory streams do not wait on it. Raises BadOperation for a closed or default-constructed reader.

• proc deadline(w: Writer): Deadline

  The writer's standing I/O deadline, shared with its paired reader. Raises BadOperation for a closed or default-constructed writer.

• proc renew(r: var Reader; deadline: Deadline)

  Replace the standing I/O deadline; never clears it. A paired writer observes the same deadline. Raises BadOperation if the reader is closed or default-constructed. This does not resume a failed partial write.

• proc renew(w: var Writer; deadline: Deadline)

  Replace the shared I/O deadline through the writer. Raises BadOperation if the writer is closed or default-constructed.

• proc buffered(r: Reader): int64

  Decoded bytes not yet consumed.

• proc peek(r: Reader): openArray[char]

  A view of the decoded bytes not yet consumed. No I/O or copying. Reader mutations invalidate the view.

• proc consume`body(r`b: var Reader; n`b: int64)

  Drop the first n bytes of peek, without I/O.

• proc consume(r: var Reader; n: int64)

  Drop the first n bytes of peek, without I/O.

• proc fill(r: var Reader): int64

  Append more decoded bytes, preserving the unread tail and compacting consumed bytes first. Returns the number added, or 0 at source or adapter end even if unread bytes remain. Raises what read raises.

  Unlike read, this can add bytes while others are still buffered. The caller must consume them or bound how much it allows to accumulate.

• proc read(r: var Reader; dest: var openArray[char]): int64

  Up to dest.len bytes; 0 is the end of the data.

• proc readLine(r: var Reader): string

  One line without its \n and a trailing \r. At the end of the data the last, unterminated line is returned, then "".

• proc readAll(r: var Reader): string

  Everything up to the end of the data.

• proc close(r: var Reader)

  Optional: the destructor does the same.

• proc write(w: var Writer; data: openArray[char])
• proc write(w: var Writer; data: string)
• proc flush(w: var Writer)

  Everything written so far goes down (and, for a connection, out).

• proc scratch(w: var Writer; n: int64): var string

  The writer's own buffer, resized to n bytes for a caller that serializes a head or a frame in place before flush. Nothing is copied, and nothing is allocated once the buffer has grown to n.

  Only for a writer with nothing buffered: the scratch is the buffer, so bytes the caller had written and not flushed would be replaced. Raises BadOperation when it is closed, finished or has pending bytes. The caller has to fill all n bytes.

• proc grow(w: var Writer; n: int64): var openArray[char]

  n more bytes at the end of the writer's buffer, for a caller that serializes a head or a frame in place. Nothing is copied, and nothing is allocated once the buffer has grown; the caller has to fill all n bytes.

  scratch for a writer that already has bytes buffered: a run of small frames is spelled one after the other into the same buffer and reaches the kernel with one flush.

• proc close(w: var Writer)

  Optional: finishes the stream — adapter trailer, TLS close_notify, end of data for the peer — and raises if any of it fails, which the destructor cannot.

• proc abort(w: var Writer)

  Ends the writer WITHOUT a clean finish: no adapter trailer, no close_notify. For error paths, where a clean finish would hand the peer a complete-looking, truncated stream.

• proc extract(w: sink Writer): string

  The bytes of an in-memory writer (openWriter(sizeHint)), finished: adapter trailers included.

• proc setAdapter(r: var Reader; a: ref Adapter.Obj)

  Fills (or with nil empties) the reader's adapter slot. Bytes read from below but not yet handed out become the new adapter's input. Replacing a adapter that has not reached its end raises: its data would be lost.

• proc setAdapter(w: var Writer; a: ref Adapter.Obj)

  Fills (or with nil empties) the writer's adapter slot. Bytes written before go out first, through the old adapter, which writes its trailer.

• type GzipAdapter = ref GzipAdapter.Obj not nil

• type GzipAdapter.Obj = object
    fmt: Format
    reading: bool
    enc: Encoder
    dec: Decoder
    done: bool

• proc gzipAdapter(fmt: Format; level: int64): ref GzipAdapter.Obj not nil

  fmtDetect (gzip or zlib, recognised by header) is for reading only.

• method attach(a: ref GzipAdapter.Obj not nil; reading: bool)
• method run(a: ref GzipAdapter.Obj not nil; src: openArray[char]; used: var int64; dest: var string; final: bool)
• method hasMore(a: ref GzipAdapter.Obj not nil): bool
• proc openReader(p: Path): Reader

  The file at p.

• proc openReader(s: sink string): Reader

  The bytes of s.

• proc openWriter(p: Path): Writer

  The file at p, truncated.

• proc openAppending(p: Path): Writer

  The file at p, written at its end.

• proc openWriter(sizeHint: int64): Writer

  An in-memory writer; extract gives its bytes back.

• proc openStreams(fd: int32; dl: Deadline): tuple[Reader, Writer]

  The streams over an already connected, non-blocking socket, without TLS: the server-side counterpart of connect, for a caller with a listener of its own (std/httpserver). No I/O, so it can be called outside a passive chain; dl is the standing deadline. The core owns fd from here on.

• proc connect(address: string; tls: ref TlsEngine.Obj; dl: Deadline): tuple[Reader, Writer]

  A connection to address (host:port); TLS when an engine is given. For a protocol where the peer speaks first (SMTP, IMAP): the next step is reading its greeting. dl bounds DNS, TCP and TLS setup together; the returned streams have no standing deadline. Raises TimeoutError on expiry.

• proc connect(address: string; request: string; tls: ref TlsEngine.Obj; dl: Deadline): tuple[Reader, Writer]

  For a protocol where we speak first (HTTP, Redis): request is written and FLUSHED before this returns, so the next step is reading the reply — the forgotten flush that hangs both sides cannot be written. One dl covers DNS, TCP, TLS and that flush; the returned streams start with never. A failed request write aborts rather than cleanly finishing.

• proc connectReader(address: string; tls: ref TlsEngine.Obj; dl: Deadline): Reader

  Only the receiving end, e.g. a feed. The sending direction is left alone (not shut down) and closes with the reader. dl bounds construction only; use renew to set a deadline for later I/O.

• proc connectWriter(address: string; tls: ref TlsEngine.Obj; dl: Deadline): Writer

  Only the sending end, e.g. shipping logs. dl bounds construction only; use renew to set a deadline for later I/O.

• proc detachWriter(w: var Writer)

  Drops a writer WITHOUT ending its direction: no adapter trailer, no close_notify, no shutdown. For a protocol layer that has written its request and keeps only the reader (std/httpclient), where ending the direction would make many servers drop the connection.

• proc copy(dest: var Writer; src: var Reader): int64

  Moves everything src has left into dest and returns how many bytes; dest stays open. Straight from the reader's buffer into the writer.

• proc pipe(capacity: int64): tuple[Reader, Writer]

  An in-process byte pipe of capacity bytes, e.g. a body produced by another task. The writer has no buffer: what is written is readable at once. read parks while the pipe is empty and returns 0 once the writer is gone; write parks while it is full and raises BadDescriptor once the reader is gone.

• proc recordPipe(capacity: int64; recSize: int64; drop: proc (p: pointer not nil) {.nimcall.}): tuple[Reader, Writer]

  A pipe for capacity records of recSize bytes each. drop destroys a record that is never read; nil for plain bytes.

• proc hasRecordRing(w: Writer; recSize: int64): bool

  w is a recordPipe writer for recSize with nothing buffered and no adapter, so writeRecord may bypass it.

• proc hasRecordRing(r: Reader; recSize: int64): bool

  Like the writer's: readRecord may bypass r.

• proc writeRecord(w: Writer; p: pointer not nil): bool

  One record from p straight into the ring, waiting for room; only after hasRecordRing. False when the reader is gone. Safe from several threads at once.

• proc readRecord(r: Reader; p: pointer not nil): bool

  One record from the ring into p, waiting for it; only after hasRecordRing. False once the writer is gone and the ring is empty. Safe from several threads at once.

• proc tryReadRecord(r: Reader; p: pointer not nil): bool

  One record from the ring into p if one is already buffered; false when there is none, or the writer is gone. Never waits, so a task can drain what is there and then do something else with it — put a batch of frames on a socket with one flush, for one. Only after hasRecordRing, and safe from several threads at once.

• proc isOpen(r: Reader): bool

  Neither closed nor default-constructed.

• proc isOpen(w: Writer): bool

  Neither closed, finished nor default-constructed.

• proc isPipe(w: Writer): bool

  w writes into a pipe or a recordPipe.