std/selectors

Этот модуль позволяет выполнять высокоуровневое и эффективное мультиплексирование ввода-вывода.

Поддерживаемые примитивы ОС: epoll, kqueue, poll и Windows select.

Для использования потокобезопасной версии этого модуля, необходимо скомпилировать его с опциями -d:threadsafe и --threads:on.

Поддерживаемые функции: файлы, сокеты, каналы, таймеры, процессы, сигналы и пользовательские события.

Полностью поддерживаемые ОС: MacOSX, FreeBSD, OpenBSD, NetBSD, Linux (кроме Android).

Частично поддерживаемые ОС: Windows (только сокеты и пользовательские события), Solaris (файлы, сокеты, дескрипторы и пользовательские события). Android (файлы, сокеты, дескрипторы и пользовательские события).

TODO: /dev/poll, event ports и события файловой системы.

Импорты

nativesockets, oserrors

Типы

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)

Перечисление типов событий Исходный код Изменить

IOSelectorsException = object of CatchableError

Исключение, которое генерируется при возникновении ошибки IOSelectors. Исходный код Изменить

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

Объект, содержащий результат для дескриптора Исходный код Изменить

SelectEvent = object

Объект, содержащий пользовательское событие Исходный код Изменить

Selector[T] = ref object

Объект, содержащий дескрипторы для проверки состояния чтения/записи Исходный код Изменить

Константы

ioselSupportedPlatform = false

Эта константа используется для определения, поддерживает ли целевая платформа модуль ioselectors полностью. Исходный код Изменить

Процедуры

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

Закрывает определяемое пользователем событие ev. Source Edit

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

Закрывает селектор. Source Edit

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

Определяет, содержит ли селектор файловый дескриптор. Source Edit

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

Извлекает определяемые приложением данные data связанные с дескриптором fd. Если указанный дескриптор fd не зарегистрирован, будет возвращено пустое/значение по умолчанию. Source Edit

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

Извлекает файловый дескриптор базового селектора.

Для селекторов poll и select возвращается -1.

Source Edit

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

Создаёт новое определяемое пользователем событие. Source Edit

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

Создаёт новый селектор Source Edit

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

Регистрирует событие селектора ev в селекторе s.

data - это определяемые приложением данные, которые будут переданы, когда произойдёт ev.

Source Edit

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

Регистрирует файловый/сетевой дескриптор fd в селекторе s с набором событий в events. data - это определяемые приложением данные, которые будут переданы при возникновении события. Source Edit

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

Регистрирует уведомление об идентификаторе процесса (pid) (когда процесс завершился) в селекторе s.

data - это определяемые приложением данные, которые будут переданы, когда процесс с pid завершится.

Возвращает файловый дескриптор для зарегистрированного сигнала.

Source Edit

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

Регистрирует уведомление о сигнале Unix с signal в селекторе s.

data - это определяемые приложением данные, которые будут переданы при возникновении сигнала.

Возвращает файловый дескриптор для зарегистрированного сигнала.

Примечание: Эта функция не поддерживается на Windows.

Source Edit

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

Регистрирует уведомление таймера с timeout (в миллисекундах) в селекторе s.

Если oneshot равно true, таймер будет уведомлён только один раз.

Установите oneshot в false, если вам нужны периодические уведомления.

data - это определяемые приложением данные, которые будут переданы при срабатывании таймера.

Возвращает файловый дескриптор для зарегистрированного таймера.

Source Edit

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

Регистрирует специфичные для BSD/MacOSX события vnode селектора для файлового дескриптора fd и событий events. data определяемые приложением данные, которые будут переданы, когда произойдет событие vnode.

Примечание: Эта функция поддерживается только BSD и MacOSX.

Source Edit

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

Ожидает событий, зарегистрированных в селекторе s.

Аргумент timeout задаёт максимальное количество миллисекунд, в течение которых функция будет заблокирована, если события не готовы. Указание времени ожидания -1 приводит к неограниченному блокированию функции.

Возвращает список сработавших событий.

Source Edit

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

Ожидает событий, зарегистрированных в селекторе s.

Аргумент timeout задаёт максимальное количество миллисекунд, в течение которых функция будет заблокирована, если события не готовы. Указание времени ожидания -1 приводит к неограниченному блокированию функции. Все доступные события будут сохранены в массиве results.

Возвращает количество сработавших событий.

Source Edit

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

Связывает определяемые приложением данные data с дескриптором fd.

Возвращает true, если данные были успешно обновлены, false в противном случае.

Source Edit

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

Срабатывает событие ev. Source Edit

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

Отменяет регистрацию определяемого пользователем события ev из селектора s. Source Edit

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

Отменяет регистрацию файлового/сетевого дескриптора fd из селектора s. Source Edit

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

Обновляет файловый/сетевой дескриптор fd, зарегистрированный в селекторе s с новым набором событий event. Source Edit

Шаблоны

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

Возвращает true, если в селекторе нет зарегистрированных событий или дескрипторов. Исходный код Изменить

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

Получает данные приложения, назначенные дескриптором fd к value. Это value может быть изменено в рамках вызова withData.

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

Исходный код Изменить

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

Получает данные приложения, назначенные дескриптором fd к value. Это value может быть изменено в рамках вызова withData.

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

Исходный код Изменить