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.
型
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
定数
ioselSupportedPlatform = false
- This constant is used to determine whether the destination platform is fully supported by ioselectors module. ソース 編集
プロシージャ
proc newSelector[T](): Selector[T]
- Creates a new selector Source Edit
proc close[T](s: Selector[T])
- Closes the selector. ソース 編集
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. ソース 編集
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.
ソース 編集 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.
ソース 編集 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.
ソース 編集 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.
ソース 編集 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.
ソース 編集 proc newSelectEvent(): SelectEvent {...}{.raises: [], tags: [].}
- Creates a new user-defined event. ソース 編集
proc trigger(ev: SelectEvent) {...}{.raises: [], tags: [].}
- Trigger event ev. ソース 編集
proc close(ev: SelectEvent) {...}{.raises: [], tags: [].}
- Closes user-defined event ev. ソース 編集
proc unregister[T](s: Selector[T]; ev: SelectEvent)
- Unregisters user-defined event ev from selector s. ソース 編集
proc unregister[T](s: Selector[T]; fd: int | SocketHandle | cint)
- Unregisters file/socket descriptor fd from selector s. ソース 編集
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.
ソース 編集 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.
ソース 編集 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. ソース 編集
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.
ソース 編集 proc contains[T](s: Selector[T]; fd: SocketHandle | int): bool {...}{.inline.}
- Determines whether selector contains a file descriptor. ソース 編集
proc getFd[T](s: Selector[T]): int
-
Retrieves the underlying selector's file descriptor.
For poll and select selectors -1 is returned.
ソース 編集 proc register[T](s: Selector[T]; fd: int | SocketHandle; events: set[Event]; data: T) {...}{. deprecated: "use registerHandle instead".}
- registerHandle instead. Source Edit Deprecated since v0.18.0: Use
proc setEvent(ev: SelectEvent) {...}{.deprecated: "use trigger instead", raises: [], tags: [].}
-
Trigger event ev.
Deprecated since v0.18.0: Use trigger instead.
ソース 編集 proc update[T](s: Selector[T]; fd: int | SocketHandle; events: set[Event]) {...}{. 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.
ソース 編集
テンプレート
template isEmpty[T](s: Selector[T]): bool
- Returns true, if there are no registered events or descriptors in selector. ソース 編集
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
ソース 編集 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
ソース 編集