Source Edit

This module contains abstractions for various operating system resource handles.

import posix

block:
  let fd = posix.open("test.txt", O_RDWR or O_CREAT)
  assert fd != -1, "opening file failed"
  let handle = initHandle(fd.FD)
  # The handle will be closed automatically once the scope ends

Imports

private/errors, private/syscall/posix

Types

AnyFD = FD or SocketFD: A typeclass representing any OS resource handles. Source Edit
FD = distinct FDImpl: The type of the OS resource handle provided by the operating system. Source Edit
Handle[T] = object ## The file descriptor mapped to a different range that ## is invalid when zero-ed.: An object used to associate a handle with a lifetime. Source Edit
SocketFD = distinct FD: The type of the OS resource handle used for network sockets. Source Edit

Consts

InvalidFD = -1: An invalid resource handle. Source Edit

Procs

func `==`(a, b: FD): bool {.borrow, ...raises: [], tags: [], forbids: [].}: Equivalence operator for FD Source Edit
func `==`(a, b: SocketFD): bool {.borrow, ...raises: [], tags: [], forbids: [].}: Equivalence operator for SocketFD Source Edit
func `==`(a: AnyFD; b: typeof(InvalidFD)): bool {.inline.}: Equivalence operator for comparing any file descriptor with InvalidFD. Source Edit
func `==`(a: typeof(InvalidFD); b: AnyFD): bool {.inline.}: Equivalence operator for comparing any file descriptor with InvalidFD. Source Edit
proc `=copy`[T](dest: var Handle[T]; src: Handle[T]) {.error.}: Copying a file handle is forbidden. Either a ref Handle should be used or duplicate should be used to make a handle refering to the same resource. Source Edit
proc close(fd: AnyFD): Closes the resource handle fd.

If the passed resource handle is not valid, ClosedHandleDefect will be raised.
Source Edit
proc close[T](h: var Handle[T]) {.inline.}: Close the handle owned by h and invalidating it.

If h is invalid, ClosedHandleDefect will be raised.
Source Edit
func fd[T](h: Handle[T]): T {.inline.}: Returns the resource handle held by h.

The returned handle will stay valid for the duration of h.

Note: Do not close the returned handle. If ownership is wanted, use takeFd instead.
Source Edit
proc initHandle[T](fd: T): Handle[T] {.inline.}: Creates a Handle owning the passed fd. The fd shall then be freed automatically when the Handle go out of scope. Source Edit
proc newHandle[T](fd: T): ref Handle[T] {.inline.}: Creates a ref Handle owning the passed fd. The fd shall then be freed automatically when the returned ref Handle[T] is collected by the GC. Source Edit
proc setBlocking(fd: AnyFD; blocking: bool): Controls the blocking state of fd, only available on POSIX systems. Source Edit
proc setInheritable(fd: AnyFD; inheritable: bool): Controls whether fd can be inherited by a child process. Source Edit
func takeFd[T](h: var Handle[T]): T {.inline.}: Returns the resource handle held by h and release ownership to the caller. h will then be invalidated. Source Edit

Templates

template raiseClosedHandleDefect(): Raises a Defect for closing an invalid/closed handle.

Calling close() on an invalid/closed handle is extremely dangerous, as the handle could have been re-used by the operating system for an another resource requested by the application.
Source Edit

src/sys/handles

Imports

Types

Consts

Procs

Templates