selectors

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, nativesockets

Types

Selector[T] = ref object
An object which holds descriptors to be checked for read/write status Source Edit 
IOSelectorsException = object of CatchableError
Exception that is raised if an IOSelectors error occurs. 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 = true
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 successfully 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

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

© 2006–2021 Andreas Rumpf
Licensed under the MIT License.
https://nim-lang.org/docs/selectors.html