Eio

はじめに

この拡張モジュールは、非同期 POSIX I/O 機能を提供します。 Marc Lehmann による » libeio C ライブラリを利用します。

注意: この拡張モジュールは Windows 環境では利用できません。

警告

注意すべき点は、個々のリクエストが単一のスレッド内で実行され、キューに入れた一連のリクエストの実行順は基本的に不定であるということです。たとえば、次のコード片は間違っています。

例1 間違ったリクエスト

<?php
// $filename のシンボリックリンクを $link に作るリクエスト
eio_symlink($filename, $link);

// $filename を $new_filename に移動するリクエスト
eio_rename($filename, $new_filename);

// リクエストを処理します
eio_event_loop();
?>

この書き方だと、eio_rename() のほうが eio_symlink() よりも先に処理されてしまう可能性があります。そうならないようにするには、eio_rename() を eio_symlink() のコールバックの中から呼びます。

例2 リクエストコールバックからのリクエストの呼び出し

<?php
function my_symlink_done($filename, $result) {
 // $filename を $new_filename に移動するリクエスト
 eio_rename($filename, "/path/to/new-name");

 // リクエストを処理します
 eio_event_loop();
}

// $filename のシンボリックリンクを $link に作るリクエスト
eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_done", $filename);

// リクエストを処理します
eio_event_loop();
?>

あるいは、リクエストグループを作るという手もあります。

例3 リクエストコールバックからのリクエストの呼び出し

<?php
/* これは、グループリクエストが終わってから呼ばれます */
function my_grp_done($data, $result) {
 // ...
}

function my_symlink_done($filename, $result) {
 // eio_rename リクエストを作り、グループに追加します
 $req = eio_rename($filename, "/path/to/new-name");
 eio_grp_add($grp, $req);
 // もっとリクエストを追加したければ、ここで追加します
}

// リクエストグループを作ります
$grp = eio_grp("my_grp_done", "my_grp_data");

// eio_symlink リクエストを作り、グループに追加します
// $filename をコールバックに渡します
$req = eio_symlink($filename, $link,
  EIO_PRI_DEFAULT, "my_symlink_done", $filename);
eio_grp_add($grp, $req);

// リクエストを処理します
eio_event_loop();
?>

グループとは特殊な形式のリクエストのことで、通常の eio リクエストを複数積み上げることができます。これを使えば、ファイルを開いて読み込んでから閉じるといった複雑なリクエストを作れます。

バージョン 0.3.0 alpha 以降では、 libeio との通信で内部的に使う変数を eio_get_event_stream() で取得できます。この変数を使うと、他の拡張モジュールでサポートしているイベントループにバインドできます。シンプルなイベントループを作って、eio と libevent を一緒に動かしたりできるのです。

例4 eio と libevent を組み合わせる例

<?php
function my_eio_poll($fd, $events, $arg) {
    /* libevent の設定があればここに書きます .. */
    if (eio_nreqs()) {
        eio_poll();
    }
    /* .. そしてここにも書きます */
}

function my_res_cb($d, $r) {
    var_dump($r); var_dump($d);
}

$base = event_base_new();
$event = event_new();

// このストリームを使って libevent にバインドします
$fd = eio_get_event_stream();

eio_nop(EIO_PRI_DEFAULT, "my_res_cb", "nop data");
eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_res_cb", "mkdir data");
/* その他の eio_* コール ... */


// イベントフラグを設定します
event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

// イベントベースを設定します
event_base_set($event, $base);

// イベントを有効化します
event_add($event);

// イベントループを開始します
event_base_loop($base);

/* バッファつき libevent インターフェイスでも同様にできます */
?>

インストール/設定
定義済み定数
例
Eio 関数
- eio_busy — 人為的に負荷を高くする。テストやベンチマークなどで有用
- eio_cancel — リクエストを取り消す
- eio_chmod — ファイルやディレクトリのパーミッションを変更する
- eio_chown — ファイルやディレクトリのオーナーを変更する
- eio_close — ファイルを閉じる
- eio_custom — eio_* のようなカスタムリクエストを実行する
- eio_dup2 — ファイルディスクリプタを複製する
- eio_event_loop — すべてのリクエストを処理し終えるまで libeio をポールする
- eio_fallocate — 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする
- eio_fchmod — ファイルのパーミッションを変更する
- eio_fchown — ファイルのオーナーを変更する
- eio_fdatasync — ファイルのコア内の情報をストレージデバイスに同期させる
- eio_fstat — ファイルの状態を取得する
- eio_fstatvfs — ファイルシステムの状態を取得する
- eio_fsync — メモリ内でのファイルの状態をストレージデバイスに同期させる
- eio_ftruncate — ファイルを切り詰める
- eio_futime — ファイルの最終アクセス時刻と変更時刻を変更する
- eio_get_event_stream — 内部での libeio との通信に使う変数を表すストリームを取得する
- eio_get_last_error — リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す
- eio_grp — リクエストグループを作る
- eio_grp_add — リクエストをリクエストグループに追加する
- eio_grp_cancel — リクエストグループをキャンセルする
- eio_grp_limit — グループリミットを設定する
- eio_init — Eio を初期化する
- eio_link — ファイルのハードリンクを作る
- eio_lstat — ファイルの状態を取得する
- eio_mkdir — ディレクトリを作る
- eio_mknod — 特殊ファイルあるいは一般ファイルを作る
- eio_nop — 何もせず、ただリクエストのサイクルを回す
- eio_npending — 終了したけれども処理されなかったリクエストの数を返す
- eio_nready — 未処理のリクエスト数を返す
- eio_nreqs — 処理対象のリクエスト数を返す
- eio_nthreads — 現在利用中のスレッド数を返す
- eio_open — ファイルを開く
- eio_poll — 未処理のリクエストがあるかどうかを調べる
- eio_read — ファイルを、指定したオフセットから読み込む
- eio_readahead — ファイルを先読みしてページキャッシュに格納する
- eio_readdir — ディレクトリ全体を読み込む
- eio_readlink — シンボリックリンクの値を読む
- eio_realpath — 正規化された絶対パスを取得する
- eio_rename — ファイル名や場所を変更する
- eio_rmdir — ディレクトリを削除する
- eio_seek — 指定した位置にシークする
- eio_sendfile — ファイルディスクリプタ間でデータを転送する
- eio_set_max_idle — アイドルスレッドの最大数を設定する
- eio_set_max_parallel — 最大の並列スレッド数を設定する
- eio_set_max_poll_reqs — 一度のポールで行う最大のリクエスト回数を設定する
- eio_set_max_poll_time — 最大のポール時間を設定する
- eio_set_min_parallel — 最小の並列スレッド数を設定する
- eio_stat — ファイルの状態を取得する
- eio_statvfs — ファイルシステムの状態を取得する
- eio_symlink — シンボリックリンクを作る
- eio_sync — バッファのキャッシュをディスクに書き込む
- eio_sync_file_range — ファイルセグメントをディスクに同期する
- eio_syncfs — Linux の syncfs システムコールが使えれば、それを呼ぶ
- eio_truncate — ファイルを切り詰める
- eio_unlink — 名前を削除し、その名前で参照しているファイルも削除する
- eio_utime — ファイルの最終アクセス時刻と変更時刻を変更する
- eio_write — ファイルに書き込む