From 62206c2db0ddd944cd0c447492da9b0de9c476a6 Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Thu, 9 Feb 2012 22:12:12 +0100 Subject: [PATCH] Clarify API doc comments in uv.h --- include/uv.h | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/include/uv.h b/include/uv.h index f0f1ff33..0e917a19 100644 --- a/include/uv.h +++ b/include/uv.h @@ -238,15 +238,27 @@ UV_EXTERN int64_t uv_now(uv_loop_t*); /* - * The status parameter is 0 if the request completed successfully, - * and should be -1 if the request was cancelled or failed. - * Error details can be obtained by calling uv_last_error(). + * Should return a buffer that libuv can use to read data into. * - * In the case of uv_read_cb the uv_buf_t returned should be freed by the - * user. + * `suggested_size` is a hint. Returning a buffer that is smaller is perfectly + * okay as long as `buf.len > 0`. */ typedef uv_buf_t (*uv_alloc_cb)(uv_handle_t* handle, size_t suggested_size); + +/* + * `nread` is > 0 if there is data available, 0 if libuv is done reading for now + * or -1 on error. + * + * Error details can be obtained by calling uv_last_error(). UV_EOF indicates + * that the stream has been closed. + * + * The callee is responsible for closing the stream when an error happens. + * Trying to read from the stream again is undefined. + * + * The callee is responsible for freeing the buffer, libuv does not reuse it. + */ typedef void (*uv_read_cb)(uv_stream_t* stream, ssize_t nread, uv_buf_t buf); + /* * Just like the uv_read_cb except that if the pending parameter is true * then you can use uv_accept() to pull the new handle into the process. @@ -254,6 +266,7 @@ typedef void (*uv_read_cb)(uv_stream_t* stream, ssize_t nread, uv_buf_t buf); */ typedef void (*uv_read2_cb)(uv_pipe_t* pipe, ssize_t nread, uv_buf_t buf, uv_handle_type pending); + typedef void (*uv_write_cb)(uv_write_t* req, int status); typedef void (*uv_connect_cb)(uv_connect_t* req, int status); typedef void (*uv_shutdown_cb)(uv_shutdown_t* req, int status);