asyncio

nimony/lib/std/asyncio.nim

• const ReadChunk: int64
• const MaxBuffered: int64

• type File = object
    fd: int32
    deadline: Deadline
    rbuf: seq[char]
    rlen: int64
    rpos: int64

• proc =destroy(f: File)

  Closing is not something a caller has to remember: a File owns its descriptor, so the descriptor goes when the file does. A hand-written =destroy replaces the field-wise one, so the buffer is freed here too.

• proc =wasMoved(f: var File)

  The descriptor and the buffer went with the destination, so this one must neither close nor free them.

• proc =dup(x: File): File
• proc =copy(dest: var File; src: File)

  Move-only: two files over one descriptor means two owners of one fd, and whichever is destroyed first closes it under the other.

• proc budget(f: var File; dl: Deadline): Deadline

  The deadline an operation actually runs under: the file's, or a tighter one the caller supplied. earlier means a caller can never widen the budget by passing a later instant.

• proc toErr(n: int64): ErrorCode

  What a negative ring result — or a kernel32 failure — means.

• proc open(filename: string; mode: FileMode; permission: set[FilePermission]; dl: Deadline): File

  Opens a file named filename with the given mode. Raises IOError if the file cannot be opened, TimeoutError if dl arrived first. The actual open runs on the polling thread as a ring command: POSIX open(2) (submitOpen), and on Windows the backend's CreateFileW through the same op — permission there has no Win32 equivalent and is ignored.

• proc close(f: var File)

  Close now rather than at the end of the scope. Idempotent, and the destructor then has nothing left to do — which is what a config reader wants when the file is read and done long before the scope ends.

  Like the destructor, this must run on the thread that submitted the file's in-flight ops (posix closeFd cancels this lane's), so the file is opened, read and closed on one lane — one passive chain, as the whole-file helpers above are.

• proc buffered(f: File): int64

  Bytes read but not yet consumed.

• proc fill(f: var File; dl: Deadline): int64

  One read into the buffer. The bytes added, or 0 at end of stream — which is a file that has nothing more, not a failure, so it is a value and not a raise. Compacts first, then grows up to MaxBuffered.

  Raises FullError when the buffer is at its ceiling and still full, TimeoutError when the deadline arrived first, IOError otherwise.

• proc read(f: var File; dest: var openArray[char]; dl: Deadline): int64

  Fill dest, starting with whatever is already buffered. The bytes copied — fewer than asked for only at end of stream. Raises what fill raises.

• proc readLine(f: var File; dl: Deadline): string

  One line, up to and including its \n, minus the delimiter and any trailing \r. An empty result is end of stream — which is an end and not a failure. A line can arrive split across fills, so this loops on the buffer rather than assuming one read held the whole line.

• proc readAll(f: var File; dl: Deadline): string

  Every byte to end of stream, consuming the buffer as it goes so memory stays bounded by MaxBuffered however big the file is.

• proc readFile(filename: string; dl: Deadline): string

  Opens filename, reads its entire contents and closes the file. Raises IOError if the file cannot be opened.

• proc writeAll(f: var File; buf: pointer not nil; len: int64; dl: Deadline)

  Write every byte or raise. A short write is possible at end of disk the way it is at a full peer buffer, so it loops.

• proc write(f: var File; data: openArray[char]; dl: Deadline)

  Write bytes already in memory. Nothing is copied.

• proc writeLine(f: var File; line: string; dl: Deadline)

  write(line) followed by a \n.

• proc writeFile(filename: string; content: string; permission: set[FilePermission]; dl: Deadline)

  Opens filename for writing, writes content, and closes the file. Raises IOError if the file cannot be opened.

• proc getFilePos(f: var File): int64

  The current position of the read pointer; the file's first byte is zero.

• proc setFilePos(f: var File; pos: int64; relativeTo: FileSeekPos)

  Sets the position of the read pointer. The read buffer is discarded: its bytes were read ahead of where the pointer is going and must not be served anymore.