selectors

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

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

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

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

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

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

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

Импорты

os, nativesockets

Типы

Selector[T] = ref object

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

IOSelectorsException = object of CatchableError

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

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)

Перечисление, содержащее типы событий Исходный код Редактировать

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

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

SelectEvent = object

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

Константы

ioselSupportedPlatform = true

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

Процедуры

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

Создает новый селектор Исходный код Редактировать

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

Закрывает селектор. Исходный код Редактировать

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

Регистрирует дескриптор файла/сокета fd в селекторе s с событиями, заданными в events. Данные data определяются приложением и передаются при срабатывании события. Исходный код Редактировать

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

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

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

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

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

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

Данные data определяются приложением и передаются при срабатывании таймера.

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

Исходный код Редактировать

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

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

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

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

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

Исходный код Редактировать

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

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

Данные data определяются приложением и передаются при завершении процесса с pid.

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

Исходный код Редактировать

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

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

Данные data определяются приложением и передаются при наступлении ev.

Исходный код Редактировать

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

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

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

Исходный код Редактировать

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

Создает новое пользовательское событие. Исходный код Редактировать

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

Срабатывает событие ev. Исходный код Редактировать

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

Закрывает пользовательское событие ev. Исходный код Редактировать

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

Удаляет пользовательское событие ev из селектора s. Исходный код Редактировать

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

Удаляет дескриптор файла/сокета fd из селектора s. Исходный код Редактировать

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

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

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

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

Исходный код Редактировать

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

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

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

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

Исходный код Редактировать

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

Получает пользовательские данные data, связанные с дескриптором fd. Если указанный дескриптор fd не зарегистрирован, возвращается пустое/стандартное значение. Исходный код Редактировать

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

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

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

Исходный код Редактировать

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

Определяет, содержит ли селектор дескриптор файла. Исходный код Редактировать

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

Получает базовый дескриптор файла селектора.

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

Исходный код Редактировать

Шаблоны

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

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

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

Исходный код Редактировать

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

Исходный код Редактировать