uv_stream_t — ストリームハンドル¶

データ型¶

type uv_stream_t¶

ストリームハンドルの型です。

type uv_connect_t¶

接続リクエストの型です。

type uv_shutdown_t¶

シャットダウンリクエストの型です。

type uv_write_t¶

書き込みリクエストの型です。この型のオブジェクトを再利用するときは、十分注意してください。ストリームが非ブロッキングモードの場合、uv_writeで送った書き込みリクエストはキューに入ります。この時点でオブジェクトを再利用すると、未定義動作になります。uv_write_tオブジェクトを安全に再利用できるのは、uv_writeへ渡したコールバックが呼び出された後だけです。

typedef void (*uv_read_cb)(uv_stream_t *stream, ssize_t nread, const uv_buf_t *buf)¶

ストリームからデータを読み取ったときに呼び出されるコールバックです。

nreadは、利用できるデータがあれば0より大きく、エラー時は0未満です。EOFに達すると、nreadは、UV_EOFに設定されます。nread < 0の場合、bufパラメーターが有効なバッファを指していない可能性があります。その場合、buf.lenと、buf.baseは両方とも0に設定されます。

注記

nreadが0の場合もありますが、エラーやEOFを意味しません。これはread(2)でEAGAINまたはEWOULDBLOCKが返る場合と同等です。

エラーが発生したときは、コールバック側が、uv_read_stop()または、uv_close()を呼び出してストリームを停止または閉じる責任があります。そのストリームから再び読み取ろうとした場合の動作は未定義です。

バッファの解放はコールバック側の責任であり、libuvは再利用しません。エラー時には、バッファがヌルバッファ、つまり、buf->base == NULLかつ、buf->len == 0の場合があります。

typedef void (*uv_write_cb)(uv_write_t *req, int status)¶

ストリームにデータを書き込んだ後に呼び出されるコールバックです。statusは、成功時は0、それ以外は0未満です。

typedef void (*uv_connect_cb)(uv_connect_t *req, int status)¶

次の関数、uv_connect()で開始した接続が完了した後に呼び出されるコールバックです。statusは、成功時は0、それ以外は0未満です。

typedef void (*uv_shutdown_cb)(uv_shutdown_t *req, int status)¶

シャットダウンリクエストが完了した後に呼び出されるコールバックです。statusは、成功時は0、それ以外は0未満です。

typedef void (*uv_connection_cb)(uv_stream_t *server, int status)¶

ストリームサーバーに接続が到着したときに呼び出されるコールバックです。ユーザーは、uv_accept()を呼び出して接続を受け付けられます。statusは、成功時は0、それ以外は0未満です。

API¶

int uv_shutdown(uv_shutdown_t *req, uv_stream_t *handle, uv_shutdown_cb cb)¶

双方向ストリームの送信側、つまり書き込み側をシャットダウンします。保留中の書き込みリクエストの完了を待ちます。handleは、初期化済みのストリームを指す必要があります。reqは、未初期化のシャットダウンリクエスト構造体でなければなりません。cbは、シャットダウン完了後に呼び出されます。

int uv_listen(uv_stream_t *stream, int backlog, uv_connection_cb cb)¶

接続の待ち受けを開始します。backlogは、カーネルがキューに入れられる接続数を表し、listen(2)と同じです。新しい接続が到着すると、uv_connection_cbコールバックが呼び出されます。

int uv_accept(uv_stream_t *server, uv_stream_t *client)¶

この関数は、uv_listen()と組み合わせて接続を受け付けるために使います。uv_connection_cbを受け取った後に呼び出して、接続を受け付けてください。この関数を呼び出す前に、clientハンドルを初期化する必要があります。0未満の戻り値はエラーを示します。

次のコールバック、uv_connection_cbが呼び出された場合、最初の呼び出しではこの関数の成功が保証されます。複数回使おうとすると、失敗することがあります。そのため、uv_connection_cbの呼び出しごとに、この関数を1回だけ呼び出すことを推奨します。

注記

serverと、clientは、同じループで動作するハンドルでなければなりません。

int uv_read_start(uv_stream_t *stream, uv_alloc_cb alloc_cb, uv_read_cb read_cb)¶

受信ストリームからデータを読み取ります。uv_read_cbコールバックは、読み取るデータがなくなるか、uv_read_stop()が呼び出されるまで、繰り返し呼び出されます。

バージョン1.38.0での変更: uv_read_start()を2回呼び出した場合は、一貫して、UV_EALREADYを返し、ストリームが閉じる処理中の場合は、UV_EINVALを返すようになりました。以前のlibuvでは、UV_EALREADYはWindowsでは返しましたがUNIXでは返さず、UV_EINVALはUNIXでは返しましたがWindowsでは返しませんでした。

int uv_read_stop(uv_stream_t*)¶

ストリームからのデータの読み取りを停止します。uv_read_cbコールバックは、以後呼び出されません。

この関数は冪等であり、停止したストリームでも安全に呼び出せます。

この関数は常に成功するため、戻り値の検査は不要です。0以外の戻り値は、WindowsのそのTTYで次の入力イベントが起きるまで、リソースの解放完了が保留されている可能性を示しており、失敗を示すものではありません。

int uv_write(uv_write_t *req, uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs, uv_write_cb cb)¶

ストリームへデータを書き込みます。バッファは順番に書き込まれます。例:

void cb(uv_write_t* req, int status) {
    /* Logic which handles the write result */
}

uv_buf_t a[] = {
    { .base = "1", .len = 1 },
    { .base = "2", .len = 1 }
};

uv_buf_t b[] = {
    { .base = "3", .len = 1 },
    { .base = "4", .len = 1 }
};

uv_write_t req1;
uv_write_t req2;

/* writes "1234" */
uv_write(&req1, stream, a, 2, cb);
uv_write(&req2, stream, b, 2, cb);

注記

バッファが指すメモリーは、コールバックが呼び出されるまで有効でなければなりません。この条件は、uv_write2()にも適用されます。

int uv_write2(uv_write_t *req, uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs, uv_stream_t *send_handle, uv_write_cb cb)¶

パイプを通じてハンドルを送るための、拡張された書き込み関数です。パイプは、ipc == 1として初期化する必要があります。

注記

send_handleは、UnixではTCP・pipe・UDPのハンドル、WindowsではTCPのハンドルでなければなりません。サーバーまたは接続、つまり待ち受け中か接続済みの状態である必要があります。バインド済みのソケットやパイプは、サーバーとみなされます。

int uv_try_write(uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs)¶

次の関数、uv_write()と同様ですが、即座に完了できない場合は、書き込みリクエストをキューに入れません。

次のいずれかを返します。

• 0より大きい値: 書き込んだバイト数です。渡したバッファのサイズより小さいことがあります。

• 0未満の値: 負のエラーコードです。UV_EAGAINは、すぐにデータを送れない場合に返します。

int uv_try_write2(uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs, uv_stream_t *send_handle)¶

次の関数、uv_try_write()と同様であり、c:func:uv_write2のように、パイプを通じてハンドルを送る拡張書き込み関数です。

Windowsではハンドルの送信を試みる機能をサポートせず、UV_EAGAINを返します。

バージョン1.42.0で追加。

size_t uv_write_nwritten(const uv_write_t *req)¶

書き込みリクエストによって書き込まれたバイト数を返します。書き込みコールバック（uv_write_cb）の中から呼び出した場合だけ有効です。

主に、uv_cancel()によって書き込みがキャンセルされ、コールバックが、UV_ECANCELEDのステータスを受け取ったときに、キャンセル前に実際に書き込まれたバイト数を確認するために役立ちます。キャンセルが効く前にカーネルが書き込みを処理し終えた場合は、キャンセルした書き込みでも成功したり、別のエラーで失敗したりすることがある点に注意してください。

バージョン1.53.0で追加。

int uv_is_readable(const uv_stream_t *handle)¶

ストリームが読み取り可能なら1、それ以外なら0を返します。

int uv_is_writable(const uv_stream_t *handle)¶

ストリームが書き込み可能なら1、それ以外なら0を返します。

int uv_stream_set_blocking(uv_stream_t *handle, int blocking)¶

ストリームのブロッキングモードを有効または無効にします。

ブロッキングモードを有効にすると、すべての書き込みが同期的に完了します。それ以外のインターフェイスは変わりません。たとえば、操作の完了や失敗は、引き続き非同期に呼び出すコールバックを通じて通知します。

警告

このAPIへ過度に依存することは推奨しません。将来、大きく変わる可能性があります。

現在、Windowsでは、uv_pipe_tのハンドルでだけ動作します。UNIX系プラットフォームでは、すべての、uv_stream_tハンドルをサポートします。

また、libuvは現在、書き込みリクエストをすでに送った後でブロッキングモードを変更した場合の順序を保証しません。そのため、ストリームを開くか作成した直後に、ブロッキングモードを設定することを推奨します。

バージョン1.4.0での変更: UNIXの実装を追加しました。

size_t uv_stream_get_write_queue_size(const uv_stream_t *stream)¶

戻り値は、stream->write_queue_sizeです。

バージョン1.19.0で追加。