This module implements asynchronous file reading and writing.

import std/[asyncfile, asyncdispatch, os]
proc main() {.async.} =
  var file = openAsync(getTempDir() / "foobar.txt", fmReadWrite)
  await file.write("test")
  file.setFilePos(0)
  let data = await file.readAll()
  doAssert data == "test"
  file.close()
waitFor main()

Imports

asyncdispatch, os, winlean

Types

AsyncFile = ref object

Source Edit

Procs

proc close(f: AsyncFile) {....raises: [OSError], tags: [], forbids: [].}

Closes the file specified. Source Edit

proc getFilePos(f: AsyncFile): int64 {....raises: [], tags: [], forbids: [].}

Retrieves the current position of the file pointer that is used to read from the specified file. The file’s first byte has the index zero. Source Edit

proc getFileSize(f: AsyncFile): int64 {....raises: [OSError], tags: [], forbids: [].}

Retrieves the specified file’s size. Source Edit

proc newAsyncFile(fd: AsyncFD): AsyncFile {....raises: [OSError], tags: [],
    forbids: [].}

Creates AsyncFile with a previously opened file descriptor fd. Source Edit

proc openAsync(filename: string; mode = fmRead): AsyncFile {....raises: [OSError],
    tags: [], forbids: [].}

Opens a file specified by the path in filename using the specified FileMode mode asynchronously. Source Edit

proc read(f: AsyncFile; size: int): Future[string] {.
    ...raises: [ValueError, Exception], tags: [RootEffect], forbids: [].}

Read size bytes from the specified file asynchronously starting at the current position of the file pointer. size should be greater than zero.

If the file pointer is past the end of the file then an empty string is returned.

Source Edit

proc readAll(f: AsyncFile): Future[string] {....stackTrace: false,
    raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}

Reads all data from the specified file. Source Edit

proc readBuffer(f: AsyncFile; buf: pointer; size: int): Future[int] {.
    ...raises: [ValueError, Exception], tags: [RootEffect], forbids: [].}

Read size bytes from the specified file asynchronously starting at the current position of the file pointer.

If the file pointer is past the end of the file then zero is returned and no bytes are read into buf

Source Edit

proc readLine(f: AsyncFile): Future[string] {....stackTrace: false,
    raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}

Reads a single line from the specified file asynchronously. Source Edit

proc readToStream(f: AsyncFile; fs: FutureStream[string]): owned(
    Future[void]) {....stackTrace: false, raises: [Exception], tags: [RootEffect],
                    forbids: [].}

Writes data to the specified future stream as the file is read. Source Edit

proc setFilePos(f: AsyncFile; pos: int64) {....raises: [], tags: [], forbids: [].}

Sets the position of the file pointer that is used for read/write operations. The file’s first byte has the index zero. Source Edit

proc setFileSize(f: AsyncFile; length: int64) {....raises: [OSError], tags: [],
    forbids: [].}

Set a file length. Source Edit

proc write(f: AsyncFile; data: string): Future[void] {....raises: [Exception],
    tags: [RootEffect], forbids: [].}

Writes data to the file specified asynchronously.

The returned Future will complete once all data has been written to the specified file.

Source Edit

proc writeBuffer(f: AsyncFile; buf: pointer; size: int): Future[void] {.
    ...raises: [Exception], tags: [RootEffect], forbids: [].}

Writes size bytes from buf to the file specified asynchronously.

The returned Future will complete once all data has been written to the specified file.

Source Edit

proc writeFromStream(f: AsyncFile; fs: FutureStream[string]): owned(
    Future[void]) {....stackTrace: false, raises: [Exception], tags: [RootEffect],
                    forbids: [].}

Reads data from the specified future stream until it is completed. The data which is read is written to the file immediately and freed from memory.

This procedure is perfect for saving streamed data to a file without wasting memory.

Source Edit