Abstractions for operating system pipes and FIFOs (named pipes).
Types
AnyPipe = AnyReadPipe or AnyWritePipe
- Typeclass for all Pipe variants. Source Edit
AnyReadPipe = AsyncReadPipe or ReadPipe
- Typeclass for all ReadPipe variants. Source Edit
AnyWritePipe = AsyncWritePipe or WritePipe
- Typeclass for all WritePipe variants. Source Edit
AsyncReadPipe = distinct AsyncFile
- The type used for the asynchronous read end of the pipe. Source Edit
AsyncWritePipe = distinct AsyncFile
- The type used for the asynchronous write end of the pipe. Source Edit
Procs
proc newAsyncPipe(flags: set[FileFlag] = {}): tuple[rd: AsyncReadPipe, wr: AsyncWritePipe] {.inline, ...raises: [OSError], tags: [], forbids: [].}
-
A shortcut for creating an anonymous pipe with both ends being asynchronous.
Asynchronous pipe endpoints should only be passed to processes that are aware of them.
See newPipe() for more details.
Source Edit proc newPipe(Rd: typedesc[AnyReadPipe] = ReadPipe; Wr: typedesc[AnyWritePipe] = WritePipe; flags: set[FileFlag] = {}): tuple[ rd: Rd:type, wr: Wr:type]
-
Creates a new anonymous pipe.
Returns a tuple containing the read and write endpoints of the pipe. The generic parameters Rd and Wr dictate the type of the endpoints.
For usage as standard input/output for child processes, it is recommended to use a synchronous pipe endpoint. The parent may use either an asynchronous or synchronous endpoint at their discretion. See the section below for more details.
Only the flag ffInheritable is supported.
Platform specific details
- On Windows, this function is implemented using an uniquely named pipe, where the server handle is always the read handle, and the write handle is always the client. The server-client distinction doesn't matter for most usage, however.
- On Windows, the asynchronous handles are created with FILE_FLAG_OVERLAPPED set, which require "overlapped" operations to be done on them (it is possible to perform "non-overlapped" I/O on them, but it is dangerous). Passing them to a process not expecting asynchronous I/O is discouraged.
- On POSIX, while the asynchronous handles can always be used synchronously in certain programs (ie. by loop on EAGAIN), it is at the cost of multiple syscalls instead of one single blocking syscall. Passing them to a process not expecting asynchronous I/O will result in reduced performance.
Templates
template close(p: AnyPipe)
-
Closes and invalidates the pipe endpoint p.
This procedure is borrowed from files.close(). See the borrowed symbol's documentation for more details.
Source Edit template read(rp: AsyncReadPipe; buf: ptr UncheckedArray[byte]; bufLen: Natural): int
-
Reads up to bufLen bytes from pipe rp into buf.
This procedure is borrowed from files.read(). See the borrowed symbol's documentation for more details.
Source Edit template read[T: byte or char](rp: ReadPipe; b: var openArray[T]): int
-
Reads up to b.len bytes from pipe rp into b.
This procedure is borrowed from files.read(). See the borrowed symbol's documentation for more details.
Source Edit template read[T: string or seq[byte]](rp: AsyncReadPipe; b: ref T): int
-
Reads up to b.len bytes from pipe rp into b.
This procedure is borrowed from files.read(). See the borrowed symbol's documentation for more details.
Source Edit template write(wp: AsyncWritePipe; buf: ptr UncheckedArray[byte]; bufLen: Natural): int
-
Writes bufLen bytes from the buffer pointed to by buf into the pipe wp.
This procedure is borrowed from files.write(). See the borrowed symbol's documentation for more details.
Source Edit template write[T: byte or char](wp: WritePipe; b: openArray[T]): int
-
Writes the contents of array b into the pipe wp.
This procedure is borrowed from files.write(). See the borrowed symbol's documentation for more details.
Source Edit template write[T: string or seq[byte]](wp: AsyncWritePipe; b: ref T): int
-
Writes the contents of array b into the pipe wp.
This procedure is borrowed from files.write(). See the borrowed symbol's documentation for more details.
Source Edit template write[T: string or seq[byte]](wp: AsyncWritePipe; b: T): int
-
Writes the contents of array b into the pipe wp. b will be copied.
This procedure is borrowed from files.write(). See the borrowed symbol's documentation for more details.
Source Edit