From ed118836c42b48947ed0d04c3323ac37dcb5fbed Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Wed, 17 Aug 2011 00:42:44 -0700 Subject: [PATCH] Improve docs --- include/uv.h | 221 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 151 insertions(+), 70 deletions(-) diff --git a/include/uv.h b/include/uv.h index ea3e1751..0d7bc857 100644 --- a/include/uv.h +++ b/include/uv.h @@ -19,6 +19,8 @@ * IN THE SOFTWARE. */ +/* See uv_init for an introduction. */ + #ifndef UV_H #define UV_H #ifdef __cplusplus @@ -64,7 +66,50 @@ typedef struct uv_connect_s uv_connect_t; #endif -/* The status parameter is 0 if the request completed successfully, +/* + * This function must be called before any other functions in libuv. + * + * At the moment libuv is single threaded but this will likely change in the + * near future. Basically it will change by uv_init() taking a 'loop' + * argument and all other _init having a first argument as the the 'loop'. + * + * All functions besides uv_run() are non-blocking. + * + * All callbacks in libuv are made asynchronously. That is they are never + * made by the function that takes them as a parameter. + */ +void uv_init(); + +/* + * This function starts the event loop. It blocks until the reference count + * of the loop drops to zero. + */ +int uv_run(); + +/* + * Manually modify the event loop's reference count. Useful if the user wants + * to have a handle or timeout that doesn't keep the loop alive. + */ +void uv_ref(); +void uv_unref(); + +void uv_update_time(); +int64_t uv_now(); + +/* + * Most functions return boolean: 0 for success and -1 for failure. + * On error the user should then call uv_last_error() to determine + * the error code. + */ +uv_err_t uv_last_error(); +char* uv_strerror(uv_err_t err); +const char* uv_err_name(uv_err_t err); + + + + +/* + * The status parameter is 0 if the request completed successfully, * and should be -1 if the request was cancelled or failed. * For uv_close_cb, -1 means that the handle was closed due to an error. * Error details can be obtained by calling uv_last_error(). @@ -191,11 +236,15 @@ UV_PRIVATE_REQ_TYPES /* + * uv_shutdown_t is a subclass of uv_req_t + * * Shutdown the outgoing (write) side of a duplex stream. It waits for * pending write requests to complete. The handle should refer to a * initialized stream. req should be an uninitalized shutdown request * struct. The cb is a called after shutdown is complete. */ +int uv_shutdown(uv_shutdown_t* req, uv_stream_t* handle, uv_shutdown_cb cb); + struct uv_shutdown_s { UV_REQ_FIELDS uv_stream_t* handle; @@ -203,8 +252,6 @@ struct uv_shutdown_s { UV_SHUTDOWN_PRIVATE_FIELDS }; -int uv_shutdown(uv_shutdown_t* req, uv_stream_t* handle, uv_shutdown_cb cb); - #define UV_HANDLE_FIELDS \ /* read-only */ \ @@ -243,7 +290,14 @@ void uv_close(uv_handle_t* handle, uv_close_cb close_cb); /* private */ \ UV_STREAM_PRIVATE_FIELDS -/* The abstract base class for all streams. */ +/* + * uv_stream_t is a subclass of uv_handle_t + * + * uv_stream is an abstract class. + * + * uv_stream_t is the parent class of uv_tcp_t, uv_pipe_t + * and soon uv_file_t. + */ struct uv_stream_s { UV_HANDLE_FIELDS UV_STREAM_FIELDS @@ -251,7 +305,8 @@ struct uv_stream_s { int uv_listen(uv_stream_t* stream, int backlog, uv_connection_cb cb); -/* This call is used in conjunction with uv_listen() to accept incoming +/* + * This call is used in conjunction with uv_listen() to accept incoming * connections. Call uv_accept after receiving a uv_connection_cb to accept * the connection. Before calling uv_accept use uv_*_init() must be * called on the client. Non-zero return value indicates an error. @@ -263,7 +318,8 @@ int uv_listen(uv_stream_t* stream, int backlog, uv_connection_cb cb); */ int uv_accept(uv_stream_t* server, uv_stream_t* client); -/* Read data from an incoming stream. The callback will be made several +/* + * Read data from an incoming stream. The callback will be made several * several times until there is no more data to read or uv_read_stop is * called. When we've reached EOF nread will be set to -1 and the error is * set to UV_EOF. When nread == -1 the buf parameter might not point to a @@ -298,10 +354,14 @@ uv_stream_t* uv_std_handle(uv_std_type type); * }; * * // writes "1234" - * uv_write(req, a, 2); - * uv_write(req, b, 2); + * uv_write(req, stream, a, 2); + * uv_write(req, stream, b, 2); * */ +int uv_write(uv_write_t* req, uv_stream_t* handle, uv_buf_t bufs[], int bufcnt, + uv_write_cb cb); + +/* uv_write_t is a subclass of uv_req_t */ struct uv_write_s { UV_REQ_FIELDS uv_write_cb cb; @@ -309,14 +369,12 @@ struct uv_write_s { UV_WRITE_PRIVATE_FIELDS }; -int uv_write(uv_write_t* req, uv_stream_t* handle, uv_buf_t bufs[], int bufcnt, - uv_write_cb cb); /* - * A subclass of uv_stream_t representing a TCP stream or TCP server. In the - * future this will probably be split into two classes - one a stream and - * the other a server. + * uv_tcp_t is a subclass of uv_stream_t + * + * Represents a TCP stream or TCP server. */ struct uv_tcp_s { UV_HANDLE_FIELDS @@ -335,6 +393,12 @@ int uv_tcp_bind6(uv_tcp_t* handle, struct sockaddr_in6); * initialized TCP handle and an uninitialized uv_connect_t*. The callback * will be made when the connection is estabished. */ +int uv_tcp_connect(uv_connect_t* req, uv_tcp_t* handle, + struct sockaddr_in address, uv_connect_cb cb); +int uv_tcp_connect6(uv_connect_t* req, uv_tcp_t* handle, + struct sockaddr_in6 address, uv_connect_cb cb); + +/* uv_connect_t is a subclass of uv_req_t */ struct uv_connect_s { UV_REQ_FIELDS uv_connect_cb cb; @@ -342,16 +406,15 @@ struct uv_connect_s { UV_CONNECT_PRIVATE_FIELDS }; -int uv_tcp_connect(uv_connect_t* req, uv_tcp_t* handle, - struct sockaddr_in address, uv_connect_cb cb); -int uv_tcp_connect6(uv_connect_t* req, uv_tcp_t* handle, - struct sockaddr_in6 address, uv_connect_cb cb); int uv_getsockname(uv_tcp_t* handle, struct sockaddr* name, int* namelen); /* - * A subclass of uv_stream_t representing a pipe stream or pipe server. + * uv_pipe_t is a subclass of uv_stream_t + * + * Representing a pipe stream or pipe server. On Windows this is a Named + * Pipe. On Unix this is a UNIX domain socket. */ struct uv_pipe_s { UV_HANDLE_FIELDS @@ -368,9 +431,11 @@ int uv_pipe_connect(uv_connect_t* req, uv_pipe_t* handle, /* - * Subclass of uv_handle_t. libev wrapper. Every active prepare handle gets - * its callback called exactly once per loop iteration, just before the - * system blocks to wait for completed i/o. + * uv_prepare_t is a subclass of uv_handle_t. + * + * libev wrapper. Every active prepare handle gets its callback called + * exactly once per loop iteration, just before the system blocks to wait + * for completed i/o. */ struct uv_prepare_s { UV_HANDLE_FIELDS @@ -385,9 +450,10 @@ int uv_prepare_stop(uv_prepare_t* prepare); /* - * Subclass of uv_handle_t. libev wrapper. Every active check handle gets - * its callback called exactly once per loop iteration, just after the - * system returns from blocking. + * uv_check_t is a subclass of uv_handle_t. + * + * libev wrapper. Every active check handle gets its callback called exactly + * once per loop iteration, just after the system returns from blocking. */ struct uv_check_s { UV_HANDLE_FIELDS @@ -402,10 +468,12 @@ int uv_check_stop(uv_check_t* check); /* - * Subclass of uv_handle_t. libev wrapper. Every active idle handle gets its - * callback called repeatedly until it is stopped. This happens after all - * other types of callbacks are processed. When there are multiple "idle" - * handles active, their callbacks are called in turn. + * uv_idle_t is a subclass of uv_handle_t. + * + * libev wrapper. Every active idle handle gets its callback called + * repeatedly until it is stopped. This happens after all other types of + * callbacks are processed. When there are multiple "idle" handles active, + * their callbacks are called in turn. */ struct uv_idle_s { UV_HANDLE_FIELDS @@ -420,7 +488,9 @@ int uv_idle_stop(uv_idle_t* idle); /* - * Subclass of uv_handle_t. libev wrapper. uv_async_send wakes up the event + * uv_async_t is a subclass of uv_handle_t. + * + * libev wrapper. uv_async_send wakes up the event * loop and calls the async handle's callback There is no guarantee that * every uv_async_send call leads to exactly one invocation of the callback; * The only guarantee is that the callback function is called at least once @@ -434,12 +504,19 @@ struct uv_async_s { int uv_async_init(uv_async_t* async, uv_async_cb async_cb); +/* + * This can be called from other threads to wake up a libuv thread. + * + * libuv is single threaded at the moment. + */ int uv_async_send(uv_async_t* async); /* - * Subclass of uv_handle_t. Wraps libev's ev_timer watcher. Used to get - * woken up at a specified time in the future. + * uv_timer_t is a subclass of uv_handle_t. + * + * Wraps libev's ev_timer watcher. Used to get woken up at a specified time + * in the future. */ struct uv_timer_s { UV_HANDLE_FIELDS @@ -448,7 +525,8 @@ struct uv_timer_s { int uv_timer_init(uv_timer_t* timer); -int uv_timer_start(uv_timer_t* timer, uv_timer_cb cb, int64_t timeout, int64_t repeat); +int uv_timer_start(uv_timer_t* timer, uv_timer_cb cb, int64_t timeout, + int64_t repeat); int uv_timer_stop(uv_timer_t* timer); @@ -472,14 +550,18 @@ int64_t uv_timer_get_repeat(uv_timer_t* timer); /* c-ares integration initialize and terminate */ int uv_ares_init_options(ares_channel *channelptr, - struct ares_options *options, - int optmask); + struct ares_options *options, + int optmask); void uv_ares_destroy(ares_channel channel); /* - * Subclass of uv_handle_t. Used for integration of getaddrinfo. + * uv_getaddrinfo_t is a subclass of uv_handle_t + * + * TODO this should be a subclass of uv_req_t + * + * Request object for uv_getaddrinfo. */ struct uv_getaddrinfo_s { UV_HANDLE_FIELDS @@ -487,12 +569,13 @@ struct uv_getaddrinfo_s { }; -/* uv_getaddrinfo - * return code of UV_OK means that request is accepted, - * and callback will be called with result. - * Other return codes mean that there will not be a callback. - * Input arguments may be released after return from this call. - * Callback must not call freeaddrinfo +/* + * Asynchronous getaddrinfo(3). + * + * Return code 0 means that request is accepted and callback will be called + * with result. Other return codes mean that there will not be a callback. + * Input arguments may be released after return from this call. Callback + * must not call freeaddrinfo. */ int uv_getaddrinfo(uv_getaddrinfo_t* handle, uv_getaddrinfo_cb getaddrinfo_cb, @@ -500,25 +583,46 @@ struct uv_getaddrinfo_s { const char* service, const struct addrinfo* hints); -/* - * Child process. Subclass of uv_handle_t. - */ +/* uv_spawn() options */ typedef struct uv_process_options_s { - uv_exit_cb exit_cb; - const char* file; + uv_exit_cb exit_cb; /* Called after the process exits. */ + const char* file; /* Path to program to execute. */ + /* + * Command line arguments. args[0] should be the path to the program. On + * Windows this uses CreateProcess which concatinates the arguments into a + * string this can cause some strange errors. See the note at + * windows_verbatim_arguments. + */ char** args; + /* + * This will be set as the environ variable in the subprocess. If this is + * NULL then the parents environ will be used. + */ char** env; + /* + * If non-null this represents a directory the subprocess should execute + * in. Stands for current working directory. + */ char* cwd; + + /* + * TODO describe how this works. + */ int windows_verbatim_arguments; + /* * The user should supply pointers to initialized uv_pipe_t structs for - * stdio. The user is reponsible for calling uv_close on them. + * stdio. This is used to to send or receive input from the subprocess. + * The user is reponsible for calling uv_close on them. */ uv_pipe_t* stdin_stream; uv_pipe_t* stdout_stream; uv_pipe_t* stderr_stream; } uv_process_options_t; +/* + * uv_process_t is a subclass of uv_handle_t + */ struct uv_process_s { UV_HANDLE_FIELDS uv_exit_cb exit_cb; @@ -536,29 +640,6 @@ int uv_spawn(uv_process_t*, uv_process_options_t options); int uv_process_kill(uv_process_t*, int signum); -/* - * Most functions return boolean: 0 for success and -1 for failure. - * On error the user should then call uv_last_error() to determine - * the error code. - */ -uv_err_t uv_last_error(); -char* uv_strerror(uv_err_t err); -const char* uv_err_name(uv_err_t err); - -void uv_init(); -int uv_run(); - -/* - * Manually modify the event loop's reference count. Useful if the user wants - * to have a handle or timeout that doesn't keep the loop alive. - */ -void uv_ref(); -void uv_unref(); - -void uv_update_time(); -int64_t uv_now(); - - /* Utility */ /* Convert string ip addresses to binary structures */