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.

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