Ev クラス

はじめに

Ev は静的クラスで、デフォルトのループへのアクセスや各種共通操作へのアクセスを提供します。

クラス概要

final class Ev {

/* 定数 */

const int Ev::FLAG_AUTO = 0;

const int Ev::FLAG_NOENV = 16777216;

const int Ev::FLAG_FORKCHECK = 33554432;

const int Ev::FLAG_NOINOTIFY = 1048576;

const int Ev::FLAG_SIGNALFD = 2097152;

const int Ev::FLAG_NOSIGMASK = 4194304;

const int Ev::RUN_NOWAIT = 1;

const int Ev::RUN_ONCE = 2;

const int Ev::BREAK_CANCEL = 0;

const int Ev::BREAK_ONE = 1;

const int Ev::BREAK_ALL = 2;

const int Ev::MINPRI = -2;

const int Ev::MAXPRI = 2;

const int Ev::READ = 1;

const int Ev::WRITE = 2;

const int Ev::TIMER = 256;

const int Ev::PERIODIC = 512;

const int Ev::SIGNAL = 1024;

const int Ev::CHILD = 2048;

const int Ev::STAT = 4096;

const int Ev::IDLE = 8192;

const int Ev::PREPARE = 16384;

const int Ev::CHECK = 32768;

const int Ev::EMBED = 65536;

const int Ev::CUSTOM = 16777216;

const int Ev::ERROR = 2147483648;

const int Ev::BACKEND_SELECT = 1;

const int Ev::BACKEND_POLL = 2;

const int Ev::BACKEND_EPOLL = 4;

const int Ev::BACKEND_KQUEUE = 8;

const int Ev::BACKEND_DEVPOLL = 16;

const int Ev::BACKEND_PORT = 32;

const int Ev::BACKEND_ALL = 63;

const int Ev::BACKEND_MASK = 65535;

/* メソッド */

final public static int backend()

final public static int depth()

final public static int embeddableBackends()

final public static void feedSignal( int $signum )

final public static void feedSignalEvent( int $signum )

final public static int iteration()

final public static float now()

final public static void nowUpdate()

final public static int recommendedBackends()

final public static void resume()

final public static void run( int $flags = ?)

final public static void sleep( float $seconds )

final public static void stop( int $how = ?)

final public static int supportedBackends()

final public static void suspend()

final public static float time()

final public static void verify()

}

定義済み定数

ループを作るときに渡すフラグ

Ev::FLAG_AUTO

デフォルトのフラグの値。

Ev::FLAG_NOENV

このフラグを使う (あるいは setuid や setgid でプログラムを実行する) と、 libev は環境変数 LIBEV_FLAGS を見ません。それ以外の場合 (デフォルト) は、 LIBEV_FLAGS が見つかった場合はその内容でフラグを上書きします。パフォーマンステストやバグの調査のときに有用です。

Ev::FLAG_FORKCHECK

libev が繰り返しのたびにフォークをチェックするようにします。毎回手動で EvLoop::fork を呼ぶことがなくなります。これを実現するために、ループ内での繰り返しの旅に getpid() を呼んでいます。そのため、繰り返しの回数が増えるとイベントループがスローダウンするかもしれませんが、通常は気になるほどではありません。このフラグの設定を上書きしたり、環境変数 LIBEV_FLAGS で指定したりすることはできません。

Ev::FLAG_NOINOTIFY

このフラグを指定すると、 libev は » ev_stat ウォッチャーに inotify API を使わなくなります。このフラグは inotify ファイルディスクリプタを節約するのに便利です。これを使わなければ、ev_stat ウォッチャーを使ったループのたびに inotify ハンドルをひとつずつ消費することになります。

Ev::FLAG_SIGNALFD

このフラグを指定すると、 libev は » ev_signal (および » ev_child ) ウォッチャーに signalfd API を使おうとします。この API はシグナルを同期的に配送し、高速に処理したりキューに入ったシグナルデータを取得できるようにしたりします。また、スレッドを使ったときのシグナル処理も、スレッド内でシグナルが適切にブロックされている限りはシンプルになります。デフォルトでは signalfd を使いません。

Ev::FLAG_NOSIGMASK

このフラグを指定すると、 libev はシグナルのマスクを変更しないようにします。具体的には、シグナルが受信されるまではブロックしないようになるということです。

これは、自前のシグナル処理をするときに便利です。また、特定のスレッドでだけシグナルを処理するという場合にも有用です。

Ev::run あるいは EvLoop::run に渡すフラグ

Ev::RUN_NOWAIT: イベントループが新しいイベントを探し、新しいイベントや未処理のイベントを処理するけれども、もしイベントが見つからない場合は、最初のループですぐに呼び出し元に制御を戻します。イベントを待つためにプロセスをブロックしたりはしません。これは、時間のかかる計算をしているときのポーリングなどに便利です。プログラムの動きを止めることなく新しいイベントを処理できます。
Ev::RUN_ONCE: イベントループが (必要なら待ち続けてでも) 新しいイベントを探し、その新しいイベントや未処理のイベントを処理します。少なくとも一つのイベントがやってくるまで (libev 自身のイベント間隔になるでしょう。そのため、ユーザー低位のコールバックが呼ばれる保証はありません) プロセスをブロックしループ処理の終了後に呼び出し元に制御を戻します。

Ev::stop あるいは EvLoop::stop に渡すフラグ

Ev::BREAK_CANCEL: ブレーク操作をキャンセルします。
Ev::BREAK_ONE: 一番内側の Ev::run (あるいは EvLoop::run ) の呼び出しを返します。
Ev::BREAK_ALL: ネストしたすべての Ev::run (あるいは EvLoop::run ) の呼び出しを返します。

ウォッチャーの優先度

Ev::MINPRI: 最小の優先度。
Ev::MAXPRI: 最大の優先度。

受信したイベントのビットマスク

Ev::READ: EvIo ウォッチャーが読み込み可能になったときのファイルディスクリプタ。
Ev::WRITE: EvIo ウォッチャーが書き込み可能になったときのファイルディスクリプタ。
Ev::TIMER: EvTimer ウォッチャーがタイムアウトしました。
Ev::PERIODIC: EvPeriodic ウォッチャーがタイムアウトしました。
Ev::SIGNAL: EvSignal::__construct のコンストラクタで指定したシグナルを受信しました。
Ev::CHILD: EvChild::__construct のコンストラクタで指定した pid が、状態の変更を受信しました。
Ev::STAT: EvStat ウォッチャーで指定したパスが、その属性を変更しました。
Ev::IDLE: 他のウォッチャーが何もすることがなくなったときに、 EvIdle ウォッチャーが動作します。
Ev::PREPARE: すべての EvPrepare ウォッチャーが、 Ev::run の開始前に起動しました。つまり、イベントループがスリープしたり新しいイベントのポーリングをしたりする直前に EvPrepare ウォッチャーが起動するということになります。
Ev::CHECK: すべての EvCheck ウォッチャーが、 Ev::run が新しいイベントをとりまとめた直後 (ただし受信したイベントのコールバックをキューに入れる前) にキューに入ります。つまり、イベントループ内で優先度が同じ (あるいはより低い) ウォッチャーより前に EvCheck ウォッチャーが起動するということになります。
Ev::EMBED: EvEmbed で指定した埋め込みイベントループのウォッチャーが注目する必要があります。
Ev::CUSTOM: まだ libev で送信したりそれ以外の使いかたをしたりはしていませんが、 libev ユーザーが ( EvWatcher::feed などで) ウォッチャーに通知するために使えます。
Ev::ERROR: 指定されていないエラーが発生し、ウォッチャーが停止しました。これが発生する原因として考えられるのは、 libev がメモリ不足でウォッチャーをきちんと開始できなかった場合やファイルディスクリプタが閉じてしまった場合などがあります。 libev は、これらに関してはアプリケーションのバグとみなします。詳細は » ANATOMY OF A WATCHER を参照ください。

バックエンドのフラグ

Ev::BACKEND_SELECT: select(2) バックエンド
Ev::BACKEND_POLL: poll(2) バックエンド
Ev::BACKEND_EPOLL: Linux 限定の epoll(7) バックエンド。2.6.9 以前のカーネルでもそれ以降のカーネルでも使えます。
Ev::BACKEND_KQUEUE: kqueue バックエンド。大半の BSD システムで利用します。 EvEmbed ウォッチャーを使って、 kqueue バックエンドのループを別のループに埋め込むことができます。たとえば、 kqueue バックエンドのループを作って、それをソケットに対してだけ使うこともできます。
Ev::BACKEND_DEVPOLL: Solaris 8 バックエンド。現時点では未実装です。
Ev::BACKEND_PORT: Solaris 10 のイベントポート機構で、規模が大きくなっても対応できます。
Ev::BACKEND_ALL: 壊れているものも含めて、すべてのバックエンドを試します。これを明示的に使うことは推奨しません。ビット演算子を使って、 Ev::BACKEND_ALL & ~ Ev::BACKEND_KQUEUE のようにするか、 Ev::recommendedBackends を使うか、あるいは何もバックエンドを指定しないようにしましょう。
Ev::BACKEND_MASK: これはバックエンドではなく、 flags の中のすべてのバックエンドビットをマスクするものです。たとえば、環境変数 LIBEV_FLAGS を変更するときに使います。

注意:
デフォルトのループの場合は、モジュールの初期化時に Ev が (もし使えれば) pthread_atfork を使って » ev_loop_fork の呼び出しを登録します。

注意:
Ev クラスには、 デフォルトのイベントループ にアクセスするメソッドが用意されています ( Ev::iteration や Ev::depth など)。 カスタムループ ( EvLoop::__construct で作ったもの) の場合、これらの値にアクセスするには EvLoop クラスのプロパティやメソッドを使います。

デフォルトのイベントループ自体のインスタンスを取得するには EvLoop::defaultLoop メソッドを使います。

Ev::backend — libev が使うバックエンドを表す整数値を返す
Ev::depth — 再帰の深さを返す
Ev::embeddableBackends — 他のイベントループに埋め込めるバックエンド群を返す
Ev::feedSignal — シグナルイベントを Ev に送る
Ev::feedSignalEvent — シグナルイベントの情報をデフォルトループに送る
Ev::iteration — デフォルトのイベントループが新しいイベントをポーリングした回数を返す
Ev::now — デフォルトのイベントループで直近の処理が始まった時刻を返す
Ev::nowUpdate — カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する
Ev::recommendedBackends — 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
Ev::resume — 一時停止していたデフォルトのイベントループを再開させる
Ev::run — イベントのチェックとデフォルトループのコールバックの呼び出しを開始する
Ev::sleep — 指定した秒数だけプロセスをブロックする
Ev::stop — デフォルトのイベントループを止める
Ev::supportedBackends — 現在の libev の構成でサポートするバックエンド群を返す
Ev::suspend — デフォルトのイベントループを一時停止する
Ev::time — epoch から現在時刻までの秒数を返す
Ev::verify — 内部の整合性をチェックする (デバッグ用)