uv_stream_t—流句柄

 

流句柄提供双工通信通道的抽象。 uv_stream_t是一个抽象类，libuv提供的形式3个实现uv_tcp_t,uv_pipe_t和uv_tty_t。

数据类型

uv_stream_t

     流句柄类型。

uv_connect_t

    连接请求类型。

uv_shutdown_t

    关机请求类型。

uv_write_t

    写请求类型。重用这种类型的对象时必须格外注意。当流处于非阻塞模式时，与一起发送的写请求uv_write将排队。此时重用对象是不确定的行为。uv_write_t仅在uv_write触发传递给回调的对象之后才可以安全地重用该对象。

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

在流上读取数据时调用的回调。

如果有可用数据，则nread为> 0；如果有错误，nread为<0。到达EOF后，nread将设置为UV_EOF。当nread <0时，buf参数可能不指向有效缓冲区；在这种情况下， buf.len和buf.base都设置为0。

注意    NREAD可能是0，这并没有指示错误或EOF。这等于EAGAIN或EWOULDBLOCK低于read(2)。

当通过调用uv_read_stop()或发生错误时，被调用方负责停止/关闭流uv_close()。尝试再次从流中读取是未定义的。

被调用方负责释放缓冲区，libuv不重用它。发生错误时，缓冲区可能是空缓冲区（其中buf-> base == NULL且buf-> len == 0）。

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

在将数据写入流之后调用回调。如果成功，状态为0，否则为<0。

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

建立连接开始后调用的回调uv_connect()。 如果成功，状态为0，否则为<0。

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

关闭请求完成后调用回调。如果成功，状态为0，否则为<0。

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

流服务器收到传入连接时调用的回调。用户可以通过调用接受连接uv_accept()。 如果成功，状态为0，否则为<0。

公共成员

size_t uv_stream_t.write_queue_size

包含等待发送的排队字节数。只读。

 

uv_stream_t* uv_connect_t.handle

指向运行此连接请求的流的指针。

 

uv_stream_t* uv_shutdown_t.handle

指向运行此关闭请求的流的指针。

 

uv_stream_t* uv_write_t.handle

指向正在运行此写请求的流的指针。

 

uv_stream_t* uv_write_t.send_handle

指向使用此写请求发送的流的指针。

也可以看看 该uv_handle_t成员也适用。

API 

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

关闭双工流的传出（写）侧。它等待挂起的写请求完成。该句柄应该是指一个初始化流。 req应该是未初始化的关闭请求结构。该cb在调用完成后调用。

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

开始监听传入的连接。backlog指示内核可能排队的连接数，与listen（2）相同。收到新的传入连接时，将cb将被调用。

int uv_accept(uv_stream_t* server, uv_stream_t* client)

该调用与uv_listen()一起用于接受传入连接。收到uv_connection_cb 并接受连接后调用此函数。在调用此函数之前，必须初始化客户端句柄。<0返回值表示错误。

当uv_connection_cb调用回调可以保证该功能将成功完成第一次。如果尝试多次使用它，则可能会失败。建议每个uv_connection_cb调用仅调用一次此函数。

注意 服务器和客户端必须是在同一循环上运行的句柄。

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

从传入流中读取数据。该uv_read_cb回调将进行几次，直到有没有更多的数据读取或 uv_read_stop()被调用。

int uv_read_stop(uv_stream_t*)

停止从流中读取数据。该uv_read_cb回调将不再被调用。

此函数是幂等的，可以在停止的流上安全地调用它。

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);

注意    缓冲区所指向的内存必须保持有效，直到调用回调为止。

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必须是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_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  阻塞）

启用或禁用流的阻止模式。

启用阻止模式后，所有写入将同步完成。否则接口将保持不变，例如，操作的完成或失败仍将通过异步进行的回调报告。

警告    不建议过多使用此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版中的新功能。