Класс EventBufferEvent

(PECL event >= 1.2.6-beta)

Введение

Класс представляет буферизированное событие Libevent.

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

Решается, что требуется записать часть данных в соединение; данные складываются в буфер
Ожидается, когда соединение станет доступным для записи.
Записывается столько данных, сколько получится.
Запоминается, сколько данных записалось и, если остались недозаписанные данные, выжидается, когда соединение снова станет доступно для записи.

Этот шаблон буферизированного ввода-вывода настолько распространён, что библиотека Libevent предоставляет встроенный механизм для него. «Буферизированное событие» состоит из транспорта, например сокета, буфера чтения и буфера записи. В отличие от стандартных событий, которые вызывают callback-функцию, когда транспорт становится доступен для чтения или записи, буферизованное событие вызывает функцию обратного вызова после считывания или записи достаточного количества данных.

Обзор класса

final class EventBufferEvent {

/* Константы */

const int READING = 1;

const int WRITING = 2;

const int EOF = 16;

const int ERROR = 32;

const int TIMEOUT = 64;

const int CONNECTED = 128;

const int OPT_CLOSE_ON_FREE = 1;

const int OPT_THREADSAFE = 2;

const int OPT_DEFER_CALLBACKS = 4;

const int OPT_UNLOCK_CALLBACKS = 8;

const int SSL_OPEN = 0;

const int SSL_CONNECTING = 1;

const int SSL_ACCEPTING = 2;

/* Свойства */

public int $fd;

public int $priority;

public readonly EventBuffer $input;

public readonly EventBuffer $output;

/* Методы */

public close(): void

public connect( string $addr ): bool

public connectHost(
     EventDnsBase $dns_base ,
     string $hostname ,
     int $port ,
     int $family = EventUtil::AF_UNSPEC
): bool

public __construct(
     EventBase $base ,
     mixed $socket = null ,
     int $options = 0 ,
     callable $readcb = null ,
     callable $writecb = null ,
     callable $eventcb = null ,
     mixed $arg = null
)

public static createPair( EventBase $base , int $options = 0 ): array

public disable( int $events ): bool

public enable( int $events ): bool

public free(): void

public getDnsErrorString(): string

public getEnabled(): int

public getInput(): EventBuffer

public getOutput(): EventBuffer

public read( int $size ): string

public readBuffer( EventBuffer $buf ): bool

public setCallbacks(
     callable $readcb ,
     callable $writecb ,
     callable $eventcb ,
     mixed $arg = ?
): void

public setPriority( int $priority ): bool

public setTimeouts( float $timeout_read , float $timeout_write ): bool

public setWatermark( int $events , int $lowmark , int $highmark ): void

public sslError(): string

public static sslFilter(
     EventBase $base ,
     EventBufferEvent $underlying ,
     EventSslContext $ctx ,
     int $state ,
     int $options = 0
): EventBufferEvent

public sslGetCipherInfo(): string

public sslGetCipherName(): string

public sslGetCipherVersion(): string

public sslGetProtocol(): string

public sslRenegotiate(): void

public static sslSocket(
     EventBase $base ,
     mixed $socket ,
     EventSslContext $ctx ,
     int $state ,
     int $options = ?
): EventBufferEvent

public write( string $data ): bool

public writeBuffer( EventBuffer $buf ): bool

}

Свойства

fd: Числовой файловый дескриптор, который связан с событием буфера. Обычно представляет связанный сокет. Дескриптор равен null, если с событием буфера не связан файловый дескриптор (сокет).
priority: Приоритет событий, через которые реализуют события буфера.
input: Нижележащий объект входящего буфера (EventBuffer).
output: Нижележащий объект исходящего буфера (EventBuffer).

Предопределённые константы

EventBufferEvent::READING: Событие произошло в момент операции чтения из bufferevent. Проверьте другие флаги для этого события.
EventBufferEvent::WRITING: Событие произошло в момент операции записи в bufferevent. Проверьте другие флаги для этого события.
EventBufferEvent::EOF: Получен признак конца файла для буферизированного события.
EventBufferEvent::ERROR: Возникла ошибка во время операции с bufferevent. Подробную информацию об ошибке получают методом EventUtil::getLastSocketErrno() и/или EventUtil::getLastSocketError().
EventBufferEvent::TIMEOUT
EventBufferEvent::CONNECTED: Запрошенное соединение с bufferevent установлено.
EventBufferEvent::OPT_CLOSE_ON_FREE: Закрыть нижележащий транспорт, когда объект буферизированного события уничтожен. Закрывается сокет, уничтожается буфер и т. д.
EventBufferEvent::OPT_THREADSAFE: Автоматически размещать блокировки для bufferevent, чтобы безопасно использовать многопоточность.
EventBufferEvent::OPT_DEFER_CALLBACKS: С этим флагом bufferevent откладывает все свои функции обратного вызова. Подробнее об отложенных функциях обратного вызова рассказывает страница » Быстрое переносимое неблокирующее сетевое программирование с Libevent и отложенными callback-функциями.
EventBufferEvent::OPT_UNLOCK_CALLBACKS: По умолчанию, когда bufferevent настроли как потокобезопасный, для буферизированного события сохраняются блокировки при запуске любых пользовательских функций обратного вызова. Установка этого флага говорит Libevent убирать блокировки при вызове этих callback-функций.
EventBufferEvent::SSL_OPEN: Подтверждение SSL завершено.
EventBufferEvent::SSL_CONNECTING: В текущий момент SSL участвует в установлении соединения как клиент.
EventBufferEvent::SSL_ACCEPTING: В текущий момент SSL участвует в установлении соединения как сервер.

Содержание

EventBufferEvent::close — Закрывает дескриптор файла, связанный с текущим событием буфера
EventBufferEvent::connect — Подключает файловый дескриптор события буфера к указанному адресу или сокету UNIX
EventBufferEvent::connectHost — Соединяется с хостом по имени с необязательным асинхронным разрешением DNS-имени
EventBufferEvent::__construct — Создаёт объект EventBufferEvent
EventBufferEvent::createPair — Создаёт два буферных события, которые связаны друг с другом
EventBufferEvent::disable — Отключает чтение, запись или и то, и другое в событии буфера
EventBufferEvent::enable — Включает чтение, запись или и то, и другое в событии буфера
EventBufferEvent::free — Освобождает событие буфера
EventBufferEvent::getDnsErrorString — Возвращает строку, которая описывает последнюю неудачную попытку поиска DNS-имени
EventBufferEvent::getEnabled — Возвращает битовую маску событий, которые в данный момент активированы для буферного события
EventBufferEvent::getInput — Возвращает базовый входной буфер, связанный с текущим буферным событием
EventBufferEvent::getOutput — Возвращает базовый выходной буфер, связанный с текущим буферным событием
EventBufferEvent::read — Читает данные буфера
EventBufferEvent::readBuffer — Считывает всё содержимое буфера ввода и помещает его в параметр buf
EventBufferEvent::setCallbacks — Назначает callback-функции для чтения, записи и события при изменении статуса
EventBufferEvent::setPriority — Присваивает приоритет bufferevent
EventBufferEvent::setTimeouts — Устанавливает время ожидания чтения и записи для события буфера
EventBufferEvent::setWatermark — Настраивает водяные знаки чтения и (или) записи
EventBufferEvent::sslError — Возвращает последнюю ошибку OpenSSL, сообщённую буферному событию
EventBufferEvent::sslFilter — Создаёт новое событие буфера SSL для отправки своих данных через другое событие буфера
EventBufferEvent::sslGetCipherInfo — Возвращает текстовое описание шифра
EventBufferEvent::sslGetCipherName — Возвращает текущее имя шифра соединения SSL
EventBufferEvent::sslGetCipherVersion — Возвращает версию шифра, используемого текущим SSL-соединением
EventBufferEvent::sslGetProtocol — Возвращает имя протокола, используемого для текущего соединения SSL
EventBufferEvent::sslRenegotiate — Сообщает буферному событию начать пересмотр SSL
EventBufferEvent::sslSocket — Создаёт новое буферное событие SSL для отправки своих данных через SSL в сокет
EventBufferEvent::write — Добавляет данные в буфер вывода буферного события
EventBufferEvent::writeBuffer — Добавляет содержимое всего буфера в буфер вывода буферного события