`uv_poll_t` — ポーリングハンドル¶

ポーリングハンドルは、次の関数と同様に、ファイル記述子の読み取り可能・書き込み可能・切断を監視するために使います: poll(2)。

ポーリングハンドルの目的は、c-aresやlibssh2など、イベントループからソケットの状態変化の通知を受ける外部ライブラリーを統合することです。他の目的でuv_poll_tを使うことは推奨しません。uv_tcp_tや、uv_udp_tなどの実装の方が、次の型よりも高速で、規模を拡大しやすいためです: uv_poll_t。特にWindowsでは、この差が大きくなります。

ポーリングハンドルは、ファイル記述子が実際には読み取り可能や書き込み可能でなくても、その状態を通知することがあります。そのため、ファイル記述子から読み取る、または書き込むときは、常にEAGAINや同等のエラーを処理できるようにしてください。

同じソケットに対し、複数のポーリングハンドルを同時にアクティブにしてはいけません。libuvがビジーループに陥ったり、他の不具合が生じたりする可能性があります。

アクティブなポーリングハンドルが監視している間は、ファイル記述子を閉じてはいけません。ハンドルがエラーを報告するだけでなく、別のソケットを監視し始める可能性もあります。ただし、uv_poll_stop()またはuv_close()を呼び出した直後なら、ファイル記述子を安全に閉じられます。

注記

Windowsでは、ポーリングハンドルで監視できるのはソケットだけです。Unixでは、次の関数が受け付けるファイル記述子を使えます: poll(2)。

注記

AIXでは、切断の監視をサポートしません。

データ型¶

type uv_poll_t¶: ポーリングハンドルの型です。

typedef void (*uv_poll_cb)(uv_poll_t *handle, int status, int events)¶: 次の関数へ渡すコールバックの型定義です: uv_poll_start()。

enum uv_poll_event¶

ポーリングイベントの型

enum uv_poll_event {
    UV_READABLE = 1,
    UV_WRITABLE = 2,
    UV_DISCONNECT = 4,
    UV_PRIORITIZED = 8
};

公開メンバー¶

該当なし

API¶

int uv_poll_init(uv_loop_t *loop, uv_poll_t *handle, int fd)¶: ファイル記述子でハンドルを初期化します。

バージョン1.2.2での変更: ファイル記述子を非ブロッキングモードに設定します。

int uv_poll_init_socket(uv_loop_t *loop, uv_poll_t *handle, uv_os_sock_t socket)¶: ソケット記述子でハンドルを初期化します。Unixでは、次の関数と同じです: uv_poll_init()。Windowsでは、SOCKETハンドルを受け取ります。

バージョン1.2.2での変更: ソケットを非ブロッキングモードに設定します。

int uv_poll_start(uv_poll_t *handle, int events, uv_poll_cb cb)¶

ファイル記述子のポーリングを開始します。eventsは、UV_READABLE、UV_WRITABLE、UV_PRIORITIZED、UV_DISCONNECTを組み合わせたビットマスクです。イベントを検出するとすぐに、statusを0に設定し、検出したイベントをeventsフィールドに設定して、コールバックを呼び出します。

次のイベント、UV_PRIORITIZEDは、sysfsの割り込みやTCPの帯域外メッセージを監視するために使います。

次のイベント、UV_DISCONNECTは、通知されない場合があり、無視しても構わないという意味で任意です。ただし、読み取りや書き込みの追加呼び出しを避けられる可能性があるため、シャットダウン処理の最適化に役立ちます。

ポーリング中にエラーが発生した場合、statusは0未満になり、UV_E*エラーコードのいずれかに対応します（エラー処理を参照）。ハンドルがアクティブな間は、ソケットを閉じてはいけません。それでも閉じた場合、エラーステータスを報告するコールバックが呼び出される可能性はありますが、その通知は保証されません。status == UV_EBADFの場合は、そのファイルハンドルのポーリングを停止し、以後イベントを報告しません。その後、ハンドルに対してuv_close()を呼び出してください。

注記

すでにアクティブなハンドルでuv_poll_start()を呼び出しても構いません。その場合、監視するイベントマスクを更新します。

注記

次のイベント、UV_DISCONNECTは指定できますが、AIXではサポートしないため、コールバックのeventsフィールドには設定されません。

注記

次のイベント、UV_READABLEまたはUV_WRITABLEが設定されている場合、対象のファイル記述子やソケットが対応する読み取り可能・書き込み可能の状態である限り、コールバックを繰り返し呼び出します。特に、次の場合が該当します。

ソケットが読み取り可能または書き込み可能になったためコールバックを呼び出したが、そのコールバックがソケットで読み取りも書き込みも行わなかった場合。
コールバックがソケットから読み取ったものの、利用可能なデータをすべては読み取らなかった場合（UV_READABLEが設定されている場合）。
コールバックがソケットへ書き込んだ後も、ソケットが書き込み可能なままであった場合（UV_WRITABLEが設定されている場合）。
ソケットに対応するポーリングハンドルでuv_poll_start()を呼び出す前からソケットが読み取り可能または書き込み可能であり、その後も状態が変わらなかった場合。

上記のすべての場合、ソケットは読み取り可能または書き込み可能な状態を維持するため、ビットマスクに設定したイベントに応じて、コールバックを再び呼び出します。この動作をレベルトリガーと呼びます。

バージョン1.9.0での変更: 次のイベントを追加しました: UV_DISCONNECT。

バージョン1.14.0での変更: 次のイベントを追加しました: UV_PRIORITIZED。

int uv_poll_stop(uv_poll_t *poll)¶: ファイル記述子のポーリングを停止します。以後、コールバックを呼び出しません。

注記

次の関数、uv_poll_stop()は呼び出すとすぐに有効になります。ソケットの状態変化の通知がすでに保留中であっても、保留中のコールバックもキャンセルします。

uv_poll_t — ポーリングハンドル¶

データ型¶

公開メンバー¶

API¶

`uv_poll_t` — ポーリングハンドル¶