# selectors

- Manual
- Standard library
- Index

Search:
Group by:

This module allows high-level and efficient I/O multiplexing.

Supported OS primitives: `epoll`, `kqueue`, `poll` and Windows `select`.

To use threadsafe version of this module, it needs to be compiled with both `-d:threadsafe` and `--threads:on` options.

Supported features: files, sockets, pipes, timers, processes, signals and user events.

Fully supported OS: MacOSX, FreeBSD, OpenBSD, NetBSD, Linux (except for Android).

Partially supported OS: Windows (only sockets and user events), Solaris (files, sockets, handles and user events). Android (files, sockets, handles and user events).

TODO: `/dev/poll`, `event ports` and filesystem events.

# Imports

os, strutils, nativesockets

# Types

    Selector[T] = ref object

  An object which holds descriptors to be checked for read/write status Source Edit

    Event {...}{.pure.} = enum
      Read,                       ## Descriptor is available for read
      Write,                      ## Descriptor is available for write
      Timer,                      ## Timer descriptor is completed
      Signal,                     ## Signal is raised
      Process,                    ## Process is finished
      Vnode,                      ## BSD specific file change
      User,                       ## User event is raised
      Error,                      ## Error occurred while waiting for descriptor
      VnodeWrite,                 ## NOTE_WRITE (BSD specific, write to file occurred)
      VnodeDelete,                ## NOTE_DELETE (BSD specific, unlink of file occurred)
      VnodeExtend,                ## NOTE_EXTEND (BSD specific, file extended)
      VnodeAttrib,                ## NOTE_ATTRIB (BSD specific, file attributes changed)
      VnodeLink,                  ## NOTE_LINK (BSD specific, file link count changed)
      VnodeRename,                ## NOTE_RENAME (BSD specific, file renamed)
      VnodeRevoke                 ## NOTE_REVOKE (BSD specific, file revoke occurred)

  An enum which hold event types Source Edit

    ReadyKey = object
      fd*: int                     ## file/socket descriptor
      events*: set[Event]          ## set of events
      errorCode*: OSErrorCode      ## additional error code information for
                            ## Error events

  An object which holds result for descriptor Source Edit

    SelectEvent = object

  An object which holds user defined event Source Edit

# Consts

    ioselSupportedPlatform = false

  This constant is used to determine whether the destination platform is fully supported by `ioselectors` module. Source Edit

# Procs

    proc newSelector[T](): Selector[T]

  Creates a new selector Source Edit

    proc close[T](s: Selector[T])

  Closes the selector. Source Edit

    proc registerHandle[T](s: Selector[T]; fd: int | SocketHandle; events: set[Event];
                          data: T)

  Registers file/socket descriptor `fd` to selector `s` with events set in `events`. The `data` is application-defined data, which will be passed when an event is triggered. Source Edit

    proc updateHandle[T](s: Selector[T]; fd: int | SocketHandle; events: set[Event])

  Update file/socket descriptor `fd`, registered in selector `s` with new events set `event`. Source Edit

    proc registerTimer[T](s: Selector[T]; timeout: int; oneshot: bool; data: T): int {...}{.
        discardable.}

  Registers timer notification with `timeout` (in milliseconds) to selector `s`.

  If `oneshot` is `true`, timer will be notified only once.

  Set `oneshot` to `false` if you want periodic notifications.

  The `data` is application-defined data, which will be passed, when the timer is triggered.

  Returns the file descriptor for the registered timer.

  Source Edit

    proc registerSignal[T](s: Selector[T]; signal: int; data: T): int {...}{.discardable.}

  Registers Unix signal notification with `signal` to selector `s`.

  The `data` is application-defined data, which will be passed when signal raises.

  Returns the file descriptor for the registered signal.

  Note: This function is not supported on `Windows`.

  Source Edit

    proc registerProcess[T](s: Selector[T]; pid: int; data: T): int {...}{.discardable.}

  Registers a process id (pid) notification (when process has exited) in selector `s`.

  The `data` is application-defined data, which will be passed when process with `pid` has exited.

  Returns the file descriptor for the registered signal.

  Source Edit

    proc registerEvent[T](s: Selector[T]; ev: SelectEvent; data: T)

  Registers selector event `ev` in selector `s`.

  The `data` is application-defined data, which will be passed when `ev` happens.

  Source Edit

    proc registerVnode[T](s: Selector[T]; fd: cint; events: set[Event]; data: T)

  Registers selector BSD/MacOSX specific vnode events for file descriptor `fd` and events `events`. `data` application-defined data, which to be passed, when vnode event happens.

  Note: This function is supported only by BSD and MacOSX.

  Source Edit

    proc newSelectEvent(): SelectEvent {...}{.raises: [], tags: [].}

  Creates a new user-defined event. Source Edit

    proc trigger(ev: SelectEvent) {...}{.raises: [], tags: [].}

  Trigger event `ev`. Source Edit

    proc close(ev: SelectEvent) {...}{.raises: [], tags: [].}

  Closes user-defined event `ev`. Source Edit

    proc unregister[T](s: Selector[T]; ev: SelectEvent)

  Unregisters user-defined event `ev` from selector `s`. Source Edit

    proc unregister[T](s: Selector[T]; fd: int | SocketHandle | cint)

  Unregisters file/socket descriptor `fd` from selector `s`. Source Edit

    proc selectInto[T](s: Selector[T]; timeout: int; results: var openArray[ReadyKey]): int

  Waits for events registered in selector `s`.

  The `timeout` argument specifies the maximum number of milliseconds the function will be blocked for if no events are ready. Specifying a timeout of `-1` causes the function to block indefinitely. All available events will be stored in `results` array.

  Returns number of triggered events.

  Source Edit

    proc select[T](s: Selector[T]; timeout: int): seq[ReadyKey]

  Waits for events registered in selector `s`.

  The `timeout` argument specifies the maximum number of milliseconds the function will be blocked for if no events are ready. Specifying a timeout of `-1` causes the function to block indefinitely.

  Returns a list of triggered events.

  Source Edit

    proc getData[T](s: Selector[T]; fd: SocketHandle | int): var T

  Retrieves application-defined `data` associated with descriptor `fd`. If specified descriptor `fd` is not registered, empty/default value will be returned. Source Edit

    proc setData[T](s: Selector[T]; fd: SocketHandle | int; data: var T): bool

  Associate application-defined `data` with descriptor `fd`.

  Returns `true`, if data was succesfully updated, `false` otherwise.

  Source Edit

    proc contains[T](s: Selector[T]; fd: SocketHandle | int): bool {...}{.inline.}

  Determines whether selector contains a file descriptor. Source Edit

    proc getFd[T](s: Selector[T]): int

  Retrieves the underlying selector's file descriptor.

  For poll and select selectors `-1` is returned.

  Source Edit

    proc register[T](s: Selector[T]; fd: int | SocketHandle; events: set[Event]; data: T) {...}{.
        deprecated: "use registerHandle instead".}

  Deprecated: use registerHandle instead
  Deprecated since v0.18.0: Use `registerHandle` instead. Source Edit

    proc setEvent(ev: SelectEvent) {...}{.deprecated: "use trigger instead", raises: [],
                                  tags: [].}

  Deprecated: use trigger instead

  Trigger event `ev`.

  Deprecated since v0.18.0: Use `trigger` instead.

  Source Edit

    proc update[T](s: Selector[T]; fd: int | SocketHandle; events: set[Event]) {...}{.
        deprecated: "use updateHandle instead".}

  Deprecated: use updateHandle instead

  Update file/socket descriptor `fd`, registered in selector `s` with new events set `event`.

  Deprecated since v0.18.0: Use `updateHandle` instead.

  Source Edit

# Templates

    template isEmpty[T](s: Selector[T]): bool

  Returns `true`, if there are no registered events or descriptors in selector. Source Edit

    template withData[T; ](s: Selector[T]; fd: SocketHandle | int; value, body: untyped)

  Retrieves the application-data assigned with descriptor `fd` to `value`. This `value` can be modified in the scope of the `withData` call.

      s.withData(fd, value) do:
        # block is executed only if ``fd`` registered in selector ``s``
        value.uid = 1000

  Source Edit

    template withData[T; ](s: Selector[T]; fd: SocketHandle | int;
                         value, body1, body2: untyped)

  Retrieves the application-data assigned with descriptor `fd` to `value`. This `value` can be modified in the scope of the `withData` call.

      s.withData(fd, value) do:
        # block is executed only if ``fd`` registered in selector ``s``.
        value.uid = 1000
      do:
        # block is executed if ``fd`` not registered in selector ``s``.
        raise

  Source Edit