c/libuv
1
0
Fork 0
mirror of https://github.com/libuv/libuv synced 2025-03-28 21:13:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: cleanup API documentation in uv.h

Browse Source
This commit is contained in:
Iñaki Baz Castillo 2014-07-05 14:13:20 +02:00
parent c44f264641
commit bf6e90f4d6
1 changed files with 209 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

395
include/uv.h
View File

@ -276,20 +276,24 @@ UV_EXTERN int uv_loop_close(uv_loop_t* loop);
/*
* Allocates and initializes a new loop.
* NOTE: This function is DEPRECATED (to be removed after 0.12), users should
* allocate the loop manually and use uv_loop_init instead.
*
* NOTE:
* This function is DEPRECATED (to be removed after 0.12), users should
* allocate the loop manually and use uv_loop_init instead.
*/
UV_EXTERN uv_loop_t* uv_loop_new(void);
/*
* Cleans up a loop once it has finished executio and frees its memory.
* NOTE: This function is DEPRECATED (to be removed after 0.12). Users should use
* uv_loop_close and free the memory manually instead.
*
* NOTE:
* This function is DEPRECATED (to be removed after 0.12). Users should use
* uv_loop_close and free the memory manually instead.
*/
UV_EXTERN void uv_loop_delete(uv_loop_t*);
/*
* Returns size of the loop struct, useful for dynamic lookup with FFI
* Returns size of the loop struct, useful for dynamic lookup with FFI.
*/
UV_EXTERN size_t uv_loop_size(void);
@ -316,10 +320,10 @@ UV_EXTERN int uv_run(uv_loop_t*, uv_run_mode mode);
UV_EXTERN int uv_loop_alive(const uv_loop_t* loop);
/*
* This function will stop the event loop by forcing uv_run to end
* as soon as possible, but not sooner than the next loop iteration.
* If this function was called before blocking for i/o, the loop won't
* block for i/o on this iteration.
* This function will stop the event loop by forcing uv_run to end as soon as
* possible, but not sooner than the next loop iteration.
* If this function was called before blocking for i/o, the loop won't block
* for i/o on this iteration.
*/
UV_EXTERN void uv_stop(uv_loop_t*);
@ -398,12 +402,12 @@ typedef void (*uv_alloc_cb)(uv_handle_t* handle,
* `nread` is > 0 if there is data available, 0 if libuv is done reading for
* now, or < 0 on error.
*
* 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 closing the stream when an error happens
* by calling uv_close(). Trying to read from the stream again is undefined.
*
* The callee is responsible for freeing the buffer, libuv does not reuse it.
* The buffer may be a null buffer (where buf->base=NULL and buf->len=0) on
* EOF or error.
* error.
*/
typedef void (*uv_read_cb)(uv_stream_t* stream,
ssize_t nread,
@ -505,17 +509,17 @@ struct uv_req_s {
};
/* Platform-specific request types */
/* Platform-specific request types. */
UV_PRIVATE_REQ_TYPES
/*
* uv_shutdown_t is a subclass of uv_req_t
* 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 uninitialized shutdown request
* struct. The cb is called after shutdown is complete.
* 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 uninitialized shutdown request struct. The cb is called
* after shutdown is complete.
*/
UV_EXTERN int uv_shutdown(uv_shutdown_t* req,
uv_stream_t* handle,
@ -540,20 +544,19 @@ struct uv_shutdown_s {
void* handle_queue[2]; \
UV_HANDLE_PRIVATE_FIELDS \
/* The abstract base class of all handles. */
/* The abstract base class of all handles. */
struct uv_handle_s {
UV_HANDLE_FIELDS
};
/*
* Returns size of various handle types, useful for FFI
* bindings to allocate correct memory without copying struct
* definitions
* Returns size of various handle types, useful for FFI bindings to allocate
* correct memory without copying struct definitions.
*/
UV_EXTERN size_t uv_handle_size(uv_handle_type type);
/*
* Returns size of request types, useful for dynamic lookup with FFI
* Returns size of request types, useful for dynamic lookup with FFI.
*/
UV_EXTERN size_t uv_req_size(uv_req_type type);
@ -566,7 +569,7 @@ UV_EXTERN size_t uv_req_size(uv_req_type type);
* by closing it with uv_close().
*
* - A uv_pipe_t, uv_tcp_t, uv_udp_t, etc. handle - basically any handle that
* deals with I/O - is active when it is doing something that involves I/O,
* deals with i/o - is active when it is doing something that involves i/o,
* like reading, writing, connecting, accepting new connections, etc.
*
* - A uv_check_t, uv_idle_t, uv_timer_t, etc. handle is active when it has
@ -601,6 +604,7 @@ UV_EXTERN void uv_close(uv_handle_t* handle, uv_close_cb close_cb);
/*
* Constructor for uv_buf_t.
*
* Due to platform differences the user cannot rely on the ordering of the
* base and len members of the uv_buf_t struct. The user is responsible for
* freeing base after the uv_buf_t is done. Return struct passed by value.
@ -617,7 +621,7 @@ UV_EXTERN uv_buf_t uv_buf_init(char* base, unsigned int len);
UV_STREAM_PRIVATE_FIELDS
/*
* uv_stream_t is a subclass of uv_handle_t
* uv_stream_t is a subclass of uv_handle_t.
*
* uv_stream is an abstract class.
*
@ -636,16 +640,16 @@ UV_EXTERN int uv_listen(uv_stream_t* stream, int backlog, uv_connection_cb cb);
* the connection. Before calling uv_accept use uv_*_init() must be
* called on the client. Non-zero return value indicates an error.
*
* When the uv_connection_cb is called it is guaranteed that uv_accept will
* When the uv_connection_cb is called it is guaranteed that uv_accept() will
* complete successfully the first time. If you attempt to use it more than
* once, it may fail. It is suggested to only call uv_accept once per
* once, it may fail. It is suggested to only call uv_accept() once per
* uv_connection_cb call.
*/
UV_EXTERN int uv_accept(uv_stream_t* server, uv_stream_t* client);
/*
* Read data from an incoming stream. The callback will be made several
* times until there is no more data to read or uv_read_stop is called.
* 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 UV_EOF.
*
* When nread < 0, the buf parameter might not point to a valid buffer;
@ -704,18 +708,19 @@ UV_EXTERN int uv_write2(uv_write_t* req,
uv_write_cb cb);
/*
* Same as `uv_write()`, but won't queue write request if it can't be completed
* Same as uv_write(), but won't queue write request if it can't be completed
* immediately.
*
* Will return either:
* - > 0: number of bytes written (can be less than the supplied buffer size)
* - > 0: number of bytes written (can be less than the supplied buffer size).
* - < 0: negative error code (UV_EAGAIN is returned if no data can be sent
* immediately)
* immediately).
*/
UV_EXTERN int uv_try_write(uv_stream_t* handle,
const uv_buf_t bufs[],
unsigned int nbufs);
/* uv_write_t is a subclass of uv_req_t */
/* uv_write_t is a subclass of uv_req_t. */
struct uv_write_s {
UV_REQ_FIELDS
uv_write_cb cb;
@ -756,15 +761,14 @@ UV_EXTERN int uv_stream_set_blocking(uv_stream_t* handle, int blocking);
/*
* Used to determine whether a stream is closing or closed.
*
* N.B. is only valid between the initialization of the handle
* and the arrival of the close callback, and cannot be used
* to validate the handle.
* N.B. is only valid between the initialization of the handle and the arrival
* of the close callback, and cannot be used to validate the handle.
*/
UV_EXTERN int uv_is_closing(const uv_handle_t* handle);
/*
* uv_tcp_t is a subclass of uv_stream_t
* uv_tcp_t is a subclass of uv_stream_t.
*
* Represents a TCP stream or TCP server.
*/
@ -796,15 +800,16 @@ UV_EXTERN int uv_tcp_keepalive(uv_tcp_t* handle,
/*
* Enable/disable simultaneous asynchronous accept requests that are
* queued by the operating system when listening for new tcp connections.
*
* This setting is used to tune a tcp server for the desired performance.
* Having simultaneous accepts can significantly improve the rate of
* accepting connections (which is why it is enabled by default) but
* may lead to uneven load distribution in multi-process setups.
* Having simultaneous accepts can significantly improve the rate of accepting
* connections (which is why it is enabled by default) but may lead to uneven
* load distribution in multi-process setups.
*/
UV_EXTERN int uv_tcp_simultaneous_accepts(uv_tcp_t* handle, int enable);
enum uv_tcp_flags {
/* Used with uv_tcp_bind, when an IPv6 address is used */
/* Used with uv_tcp_bind, when an IPv6 address is used. */
UV_TCP_IPV6ONLY = 1
};
@ -812,11 +817,11 @@ enum uv_tcp_flags {
* Bind the handle to an address and port. `addr` should point to an
* initialized struct sockaddr_in or struct sockaddr_in6.
*
* When the port is already taken, you can expect to see an UV_EADDRINUSE
* error from either uv_tcp_bind(), uv_listen() or uv_tcp_connect().
* When the port is already taken, you can expect to see an UV_EADDRINUSE error
* from either uv_tcp_bind(), uv_listen() or uv_tcp_connect().
*
* That is, a successful call to uv_tcp_bind() does not guarantee that
* the call to uv_listen() or uv_tcp_connect() will succeed as well.
* That is, a successful call to uv_tcp_bind() does not guarantee that the call
* to uv_listen() or uv_tcp_connect() will succeed as well.
*/
UV_EXTERN int uv_tcp_bind(uv_tcp_t* handle,
const struct sockaddr* addr,
@ -830,7 +835,7 @@ UV_EXTERN int uv_tcp_getpeername(const uv_tcp_t* handle,
/*
* Establish an IPv4 or IPv6 TCP connection. Provide an initialized TCP handle
* and an uninitialized uv_connect_t*. `addr` should point to an initialized
* and an uninitialized uv_connect_t*. `addr` should point to an initialized
* struct sockaddr_in or struct sockaddr_in6.
*
* The callback is made when the connection has been established or when a
@ -841,7 +846,7 @@ UV_EXTERN int uv_tcp_connect(uv_connect_t* req,
const struct sockaddr* addr,
uv_connect_cb cb);
/* uv_connect_t is a subclass of uv_req_t */
/* uv_connect_t is a subclass of uv_req_t. */
struct uv_connect_s {
UV_REQ_FIELDS
uv_connect_cb cb;
@ -862,9 +867,10 @@ enum uv_udp_flags {
* remainder was discarded by the OS. Used in uv_udp_recv_cb.
*/
UV_UDP_PARTIAL = 2,
/* Indicates if SO_REUSEADDR will be set when binding the handle.
/*
* Indicates if SO_REUSEADDR will be set when binding the handle.
* This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other
* UNIX platforms, it sets the SO_REUSEADDR flag. What that means is that
* Unix platforms, it sets the SO_REUSEADDR flag. What that means is that
* multiple threads or processes can bind to the same address without error
* (provided they all set the flag) but only the last one to bind will receive
* any traffic, in effect "stealing" the port from the previous listener.
@ -873,8 +879,7 @@ enum uv_udp_flags {
};
/*
* Called after uv_udp_send(). status 0 indicates
* success otherwise error.
* Called after uv_udp_send(). status 0 indicates success otherwise error.
*/
typedef void (*uv_udp_send_cb)(uv_udp_send_t* req, int status);
@ -883,14 +888,20 @@ typedef void (*uv_udp_send_cb)(uv_udp_send_t* req, int status);
*
* handle UDP handle.
* nread Number of bytes that have been received.
* 0 if there is no more data to read. You may
* discard or repurpose the read buffer.
* < 0 if a transmission error was detected.
* - 0 if there is no more data to read. You may discard or repurpose
* the read buffer. Note that 0 may also mean that an empty datagram
* was received (in this case `addr` is not NULL).
* - < 0 if a transmission error was detected.
* buf uv_buf_t with the received data.
* addr struct sockaddr* containing the address of the sender.
* Can be NULL. Valid for the duration of the callback only.
* flags One or more OR'ed UV_UDP_* constants.
* Right now only UV_UDP_PARTIAL is used.
* addr struct sockaddr* containing the address of the sender. Can be NULL.
* Valid for the duration of the callback only.
* flags One or more OR'ed UV_UDP_* constants. Right now only UV_UDP_PARTIAL
* is used.
*
* NOTE:
* The receive callback will be called with nread == 0 and addr == NULL when
* there is nothing to read, and with nread == 0 and addr != NULL when an empty
* UDP packet is received.
*/
typedef void (*uv_udp_recv_cb)(uv_udp_t* handle,
ssize_t nread,
@ -898,22 +909,23 @@ typedef void (*uv_udp_recv_cb)(uv_udp_t* handle,
const struct sockaddr* addr,
unsigned flags);
/* uv_udp_t is a subclass of uv_handle_t */
/* uv_udp_t is a subclass of uv_handle_t. */
struct uv_udp_s {
UV_HANDLE_FIELDS
/* read-only */
/* Number of bytes queued for sending. This field strictly shows
* how much information is currently queued.
/*
* Number of bytes queued for sending. This field strictly shows how much
* information is currently queued.
*/
size_t send_queue_size;
/* number of send requests currently in the queue awaiting to
* be processed.
/*
* Number of send requests currently in the queue awaiting to be processed.
*/
size_t send_queue_count;
UV_UDP_PRIVATE_FIELDS
};
/* uv_udp_send_t is a subclass of uv_req_t */
/* uv_udp_send_t is a subclass of uv_req_t. */
struct uv_udp_send_s {
UV_REQ_FIELDS
uv_udp_t* handle;
@ -931,16 +943,16 @@ UV_EXTERN int uv_udp_init(uv_loop_t*, uv_udp_t* handle);
* Opens an existing file descriptor or SOCKET as a udp handle.
*
* Unix only:
* The only requirement of the sock argument is that it follows the
* datagram contract (works in unconnected mode, supports sendmsg()/recvmsg(),
* etc.). In other words, other datagram-type sockets like raw sockets or
* netlink sockets can also be passed to this function.
* The only requirement of the sock argument is that it follows the datagram
* contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc).
* In other words, other datagram-type sockets like raw sockets or netlink
* sockets can also be passed to this function.
*
* This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other
* UNIX platforms, it sets the SO_REUSEADDR flag. What that means is that
* multiple threads or processes can bind to the same address without error
* (provided they all set the flag) but only the last one to bind will receive
* any traffic, in effect "stealing" the port from the previous listener.
* This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other Unix
* platforms, it sets the SO_REUSEADDR flag. What that means is that multiple
* threads or processes can bind to the same address without error (provided
* they all set the flag) but only the last one to bind will receive any
* traffic, in effect "stealing" the port from the previous listener.
* This behavior is something of an anomaly and may be replaced by an explicit
* opt-in mechanism in future versions of libuv.
*/
@ -950,7 +962,7 @@ UV_EXTERN int uv_udp_open(uv_udp_t* handle, uv_os_sock_t sock);
* Bind to an IP address and port.
*
* Arguments:
* handle UDP handle. Should have been initialized with `uv_udp_init`.
* handle UDP handle. Should have been initialized with uv_udp_init().
* addr struct sockaddr_in or struct sockaddr_in6 with the address and
* port to bind to.
* flags Indicate how the socket will be bound, UV_UDP_IPV6ONLY and
@ -972,10 +984,10 @@ UV_EXTERN int uv_udp_getsockname(uv_udp_t* handle,
*
* Arguments:
* handle UDP handle. Should have been initialized with
* `uv_udp_init`.
* multicast_addr multicast address to set membership for
* interface_addr interface address
* membership Should be UV_JOIN_GROUP or UV_LEAVE_GROUP
* uv_udp_init().
* multicast_addr multicast address to set membership for.
* interface_addr interface address.
* membership Should be UV_JOIN_GROUP or UV_LEAVE_GROUP.
*
* Returns:
* 0 on success, or an error code < 0 on failure.
@ -991,8 +1003,8 @@ UV_EXTERN int uv_udp_set_membership(uv_udp_t* handle,
*
* Arguments:
* handle UDP handle. Should have been initialized with
* `uv_udp_init`.
* on 1 for on, 0 for off
* uv_udp_init().
* on 1 for on, 0 for off.
*
* Returns:
* 0 on success, or an error code < 0 on failure.
@ -1000,12 +1012,12 @@ UV_EXTERN int uv_udp_set_membership(uv_udp_t* handle,
UV_EXTERN int uv_udp_set_multicast_loop(uv_udp_t* handle, int on);
/*
* Set the multicast ttl
* Set the multicast ttl.
*
* Arguments:
* handle UDP handle. Should have been initialized with
* `uv_udp_init`.
* ttl 1 through 255
* uv_udp_init().
* ttl 1 through 255.
*
* Returns:
* 0 on success, or an error code < 0 on failure.
@ -1014,12 +1026,12 @@ UV_EXTERN int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl);
/*
* Set the multicast interface to send on
* Set the multicast interface to send on.
*
* Arguments:
* handle UDP handle. Should have been initialized with
* `uv_udp_init`.
* interface_addr interface address
* uv_udp_init().
* interface_addr interface address.
*
* Returns:
* 0 on success, or an error code < 0 on failure.
@ -1028,12 +1040,12 @@ UV_EXTERN int uv_udp_set_multicast_interface(uv_udp_t* handle,
const char* interface_addr);
/*
* Set broadcast on or off
* Set broadcast on or off.
*
* Arguments:
* handle UDP handle. Should have been initialized with
* `uv_udp_init`.
* on 1 for on, 0 for off
* uv_udp_init().
* on 1 for on, 0 for off.
*
* Returns:
* 0 on success, or an error code < 0 on failure.
@ -1041,12 +1053,12 @@ UV_EXTERN int uv_udp_set_multicast_interface(uv_udp_t* handle,
UV_EXTERN int uv_udp_set_broadcast(uv_udp_t* handle, int on);
/*
* Set the time to live
* Set the time to live.
*
* Arguments:
* handle UDP handle. Should have been initialized with
* `uv_udp_init`.
* ttl 1 through 255
* uv_udp_init().
* ttl 1 through 255.
*
* Returns:
* 0 on success, or an error code < 0 on failure.
@ -1054,13 +1066,12 @@ UV_EXTERN int uv_udp_set_broadcast(uv_udp_t* handle, int on);
UV_EXTERN int uv_udp_set_ttl(uv_udp_t* handle, int ttl);
/*
* Send data. If the socket has not previously been bound with `uv_udp_bind,`
* it is bound to 0.0.0.0 (the "all interfaces" address) and a random
* port number.
* Send data. If the socket has not previously been bound with uv_udp_bind() it
* is bound to 0.0.0.0 (the "all interfaces" address) and a random port number.
*
* Arguments:
* req UDP request handle. Need not be initialized.
* handle UDP handle. Should have been initialized with `uv_udp_init`.
* handle UDP handle. Should have been initialized with uv_udp_init().
* bufs List of buffers to send.
* nbufs Number of buffers in `bufs`.
* addr struct sockaddr_in or struct sockaddr_in6 with the address and
@ -1078,35 +1089,30 @@ UV_EXTERN int uv_udp_send(uv_udp_send_t* req,
uv_udp_send_cb send_cb);
/*
* Same as `uv_udp_send()`, but won't queue a send request if it can't be completed
* Same as uv_udp_send(), but won't queue a send request if it can't be completed
* immediately.
*
* Will return either:
* - >= 0: number of bytes written (can be less than the supplied buffer size if the
* packet is truncated)
* - < 0: negative error code (UV_EAGAIN is returned when the message can't be sent
* immediately)
* - >= 0: number of bytes sent (it matches the given buffer size).
* - < 0: negative error code (UV_EAGAIN is returned when the message can't be
* sent immediately).
*/
UV_EXTERN int uv_udp_try_send(uv_udp_t* handle,
const uv_buf_t bufs[],
unsigned int nbufs,
const struct sockaddr* addr);
/*
* Receive data. If the socket has not previously been bound with `uv_udp_bind`
* it is bound to 0.0.0.0 (the "all interfaces" address) and a random
* port number.
* Receive data. If the socket has not previously been bound with uv_udp_bind()
* it is bound to 0.0.0.0 (the "all interfaces" address) and a random port
* number.
*
* Arguments:
* handle UDP handle. Should have been initialized with `uv_udp_init`.
* handle UDP handle. Should have been initialized with uv_udp_init().
* alloc_cb Callback to invoke when temporary storage is needed.
* recv_cb Callback to invoke with received data.
*
* Returns:
* 0 on success, or an error code < 0 on failure.
*
* Note: The receive callback will be called with nread == 0
* and addr == NULL when there is nothing to read and
* with nread == 0 and addr != NULL when an empty udp
* packet is received.
*/
UV_EXTERN int uv_udp_recv_start(uv_udp_t* handle,
uv_alloc_cb alloc_cb,
@ -1116,7 +1122,7 @@ UV_EXTERN int uv_udp_recv_start(uv_udp_t* handle,
* Stop listening for incoming datagrams.
*
* Arguments:
* handle UDP handle. Should have been initialized with `uv_udp_init`.
* handle UDP handle. Should have been initialized with uv_udp_init().
*
* Returns:
* 0 on success, or an error code < 0 on failure.
@ -1125,7 +1131,7 @@ UV_EXTERN int uv_udp_recv_stop(uv_udp_t* handle);
/*
* uv_tty_t is a subclass of uv_stream_t
* uv_tty_t is a subclass of uv_stream_t.
*
* Representing a stream for the console.
*/
@ -1137,12 +1143,12 @@ struct uv_tty_s {
/*
* Initialize a new TTY stream with the given file descriptor. Usually the
* file descriptor will be
* file descriptor will be:
* 0 = stdin
* 1 = stdout
* 2 = stderr
* The last argument, readable, specifies if you plan on calling
* uv_read_start with this stream. stdin is readable, stdout is not.
* uv_read_start() with this stream. stdin is readable, stdout is not.
*
* TTY streams which are not readable have blocking writes.
*/
@ -1157,7 +1163,7 @@ UV_EXTERN int uv_tty_set_mode(uv_tty_t*, int mode);
* To be called when the program exits. Resets TTY settings to default
* values for the next process to take over.
*
* This function is async signal-safe on UNIX platforms but can fail with error
* This function is async signal-safe on Unix platforms but can fail with error
* code UV_EBUSY if you call it when execution is inside uv_tty_set_mode().
*/
UV_EXTERN int uv_tty_reset_mode(void);
@ -1171,15 +1177,16 @@ UV_EXTERN int uv_tty_get_winsize(uv_tty_t*, int* width, int* height);
* Used to detect what type of stream should be used with a given file
* descriptor. Usually this will be used during initialization to guess the
* type of the stdio streams.
*
* For isatty() functionality use this function and test for UV_TTY.
*/
UV_EXTERN uv_handle_type uv_guess_handle(uv_file file);
/*
* uv_pipe_t is a subclass of uv_stream_t
* 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.
* Pipe. On Unix this is a Unix domain socket.
*/
struct uv_pipe_s {
UV_HANDLE_FIELDS
@ -1200,17 +1207,17 @@ UV_EXTERN int uv_pipe_init(uv_loop_t*, uv_pipe_t* handle, int ipc);
UV_EXTERN int uv_pipe_open(uv_pipe_t*, uv_file file);
/*
* Bind the pipe to a file path (UNIX) or a name (Windows.)
* Bind the pipe to a file path (Unix) or a name (Windows).
*
* Paths on UNIX get truncated to `sizeof(sockaddr_un.sun_path)` bytes,
* Paths on Unix get truncated to `sizeof(sockaddr_un.sun_path)` bytes,
* typically between 92 and 108 bytes.
*/
UV_EXTERN int uv_pipe_bind(uv_pipe_t* handle, const char* name);
/*
* Connect to the UNIX domain socket or the named pipe.
* Connect to the Unix domain socket or the named pipe.
*
* Paths on UNIX get truncated to `sizeof(sockaddr_un.sun_path)` bytes,
* Paths on Unix get truncated to `sizeof(sockaddr_un.sun_path)` bytes,
* typically between 92 and 108 bytes.
*/
UV_EXTERN void uv_pipe_connect(uv_connect_t* req,
@ -1219,12 +1226,12 @@ UV_EXTERN void uv_pipe_connect(uv_connect_t* req,
uv_connect_cb cb);
/*
* Get the name of the UNIX domain socket or the named pipe.
* Get the name of the Unix domain socket or the named pipe.
*
* A preallocated buffer must be provided. The len parameter holds the
* length of the buffer and it's set to the number of bytes written to the
* buffer on output. If the buffer is not big enough UV_ENOBUFS will be
* returned and len will contain the required size.
* A preallocated buffer must be provided. The len parameter holds the length
* of the buffer and it's set to the number of bytes written to the buffer on
* output. If the buffer is not big enough UV_ENOBUFS will be returned and len
* will contain the required size.
*/
UV_EXTERN int uv_pipe_getsockname(const uv_pipe_t* handle,
char* buf,
@ -1232,17 +1239,18 @@ UV_EXTERN int uv_pipe_getsockname(const uv_pipe_t* handle,
/*
* This setting applies to Windows only.
* Set the number of pending pipe instance handles when the pipe server
* is waiting for connections.
*
* Set the number of pending pipe instance handles when the pipe server is
* waiting for connections.
*/
UV_EXTERN void uv_pipe_pending_instances(uv_pipe_t* handle, int count);
/*
* Used to receive handles over ipc pipes.
*
* First - call `uv_pipe_pending_count`, if it is > 0 - initialize handle
* using type, returned by `uv_pipe_pending_type` and call
* `uv_accept(pipe, handle)`.
* First - call uv_pipe_pending_count(), if it is > 0 - initialize handle
* using type, returned by uv_pipe_pending_type() and call
* uv_accept(pipe, handle).
*/
UV_EXTERN int uv_pipe_pending_count(uv_pipe_t* handle);
UV_EXTERN uv_handle_type uv_pipe_pending_type(uv_pipe_t* handle);
@ -1273,7 +1281,7 @@ UV_EXTERN uv_handle_type uv_pipe_pending_type(uv_pipe_t* handle);
* but it might also start polling another socket. However the fd can be safely
* closed immediately after a call to uv_poll_stop() or uv_close().
*
* On windows only sockets can be polled with uv_poll. On unix any file
* On windows only sockets can be polled with uv_poll. On Unix any file
* descriptor that would be accepted by poll(2) can be used with uv_poll.
*/
struct uv_poll_s {
@ -1290,8 +1298,10 @@ enum uv_poll_event {
/* Initialize the poll watcher using a file descriptor. */
UV_EXTERN int uv_poll_init(uv_loop_t* loop, uv_poll_t* handle, int fd);
/* Initialize the poll watcher using a socket descriptor. On unix this is */
/* identical to uv_poll_init. On windows it takes a SOCKET handle. */
/*
* Initialize the poll watcher using a socket descriptor. On Unix this is
* identical to uv_poll_init. On windows it takes a SOCKET handle.
*/
UV_EXTERN int uv_poll_init_socket(uv_loop_t* loop,
uv_poll_t* handle,
uv_os_sock_t socket);
@ -1375,11 +1385,15 @@ UV_EXTERN int uv_idle_stop(uv_idle_t* idle);
/*
* uv_async_t is a subclass of uv_handle_t.
*
* 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 after the call to async_send. Unlike all other
* libuv functions, uv_async_send can be called from another thread.
* uv_async_send() wakes up the event loop and calls the async handle's callback.
*
* Unlike all other libuv functions, uv_async_send() can be called from another
* thread.
*
* NOTE:
* 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 after the call to async_send.
*/
struct uv_async_s {
UV_HANDLE_FIELDS
@ -1448,7 +1462,7 @@ UV_EXTERN uint64_t uv_timer_get_repeat(const uv_timer_t* handle);
/*
* uv_getaddrinfo_t is a subclass of uv_req_t
* uv_getaddrinfo_t is a subclass of uv_req_t.
*
* Request object for uv_getaddrinfo.
*/
@ -1492,7 +1506,7 @@ UV_EXTERN void uv_freeaddrinfo(struct addrinfo* ai);
/*
* uv_getnameinfo_t is a subclass of uv_req_t
* uv_getnameinfo_t is a subclass of uv_req_t.
*
* Request object for uv_getnameinfo.
*/
@ -1518,14 +1532,15 @@ UV_EXTERN int uv_getnameinfo(uv_loop_t* loop,
int flags);
/* uv_spawn() options */
/* uv_spawn() options. */
typedef enum {
UV_IGNORE = 0x00,
UV_CREATE_PIPE = 0x01,
UV_INHERIT_FD = 0x02,
UV_INHERIT_STREAM = 0x04,
/* When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
/*
* When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
* determine the direction of flow, from the child process' perspective. Both
* flags may be specified to create a duplex data stream.
*/
@ -1606,7 +1621,7 @@ enum uv_process_flags {
/*
* Do not wrap any arguments in quotes, or perform any other escaping, when
* converting the argument list into a command line string. This option is
* only meaningful on Windows systems. On unix it is silently ignored.
* only meaningful on Windows systems. On Unix it is silently ignored.
*/
UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2),
/*
@ -1619,14 +1634,14 @@ enum uv_process_flags {
UV_PROCESS_DETACHED = (1 << 3),
/*
* Hide the subprocess console window that would normally be created. This
* option is only meaningful on Windows systems. On unix it is silently
* option is only meaningful on Windows systems. On Unix it is silently
* ignored.
*/
UV_PROCESS_WINDOWS_HIDE = (1 << 4)
};
/*
* uv_process_t is a subclass of uv_handle_t
* uv_process_t is a subclass of uv_handle_t.
*/
struct uv_process_s {
UV_HANDLE_FIELDS
@ -1653,7 +1668,7 @@ UV_EXTERN int uv_spawn(uv_loop_t* loop,
/*
* Kills the process with the specified signal. The user must still
* call uv_close on the process.
* call uv_close() on the process.
*
* Emulates some aspects of Unix exit status on Windows, in that while the
* underlying process will be terminated with a status of `1`,
@ -1679,7 +1694,7 @@ UV_EXTERN int uv_kill(int pid, int signum);
/*
* uv_work_t is a subclass of uv_req_t
* uv_work_t is a subclass of uv_req_t.
*/
struct uv_work_s {
UV_REQ_FIELDS
@ -1714,7 +1729,7 @@ UV_EXTERN int uv_queue_work(uv_loop_t* loop,
* - A uv_work_t or uv_getaddrinfo_t request has its callback invoked with
* status == UV_ECANCELED.
*
* This function is currently only implemented on UNIX platforms. On Windows,
* This function is currently only implemented on Unix platforms. On Windows,
* it always returns UV_ENOSYS.
*/
UV_EXTERN int uv_cancel(uv_req_t* req);
@ -1783,15 +1798,15 @@ typedef struct {
UV_EXTERN int uv_getrusage(uv_rusage_t* rusage);
/*
* This allocates cpu_infos array, and sets count. The array
* is freed using uv_free_cpu_info().
* This allocates cpu_infos array, and sets count. The array is freed
* using uv_free_cpu_info().
*/
UV_EXTERN int uv_cpu_info(uv_cpu_info_t** cpu_infos, int* count);
UV_EXTERN void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count);
/*
* This allocates addresses array, and sets count. The array
* is freed using uv_free_interface_addresses().
* This allocates addresses array, and sets count. The array is freed
* using uv_free_interface_addresses().
*/
UV_EXTERN int uv_interface_addresses(uv_interface_address_t** addresses,
int* count);
@ -1842,7 +1857,7 @@ typedef enum {
UV_FS_FCHOWN
} uv_fs_type;
/* uv_fs_t is a subclass of uv_req_t */
/* uv_fs_t is a subclass of uv_req_t. */
struct uv_fs_s {
UV_REQ_FIELDS
uv_fs_type fs_type;
@ -1851,7 +1866,7 @@ struct uv_fs_s {
ssize_t result;
void* ptr;
const char* path;
uv_stat_t statbuf; /* Stores the result of uv_fs_stat and uv_fs_fstat. */
uv_stat_t statbuf; /* Stores the result of uv_fs_stat() and uv_fs_fstat(). */
UV_FS_PRIVATE_FIELDS
};
@ -1918,14 +1933,14 @@ UV_EXTERN int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path,
const char* new_path, uv_fs_cb cb);
/*
* This flag can be used with uv_fs_symlink on Windows
* to specify whether path argument points to a directory.
* This flag can be used with uv_fs_symlink() on Windows to specify whether
* path argument points to a directory.
*/
#define UV_FS_SYMLINK_DIR 0x0001
/*
* This flag can be used with uv_fs_symlink on Windows
* to specify whether the symlink is to be created using junction points.
* This flag can be used with uv_fs_symlink() on Windows to specify whether
* the symlink is to be created using junction points.
*/
#define UV_FS_SYMLINK_JUNCTION 0x0002
@ -2003,7 +2018,7 @@ UV_EXTERN int uv_fs_poll_getpath(uv_fs_poll_t* handle, char* buf, size_t* len);
/*
* UNIX signal handling on a per-event loop basis. The implementation is not
* Unix signal handling on a per-event loop basis. The implementation is not
* ultra efficient so don't go creating a million event loops with a million
* signal watchers.
*
@ -2058,14 +2073,16 @@ UV_EXTERN int uv_signal_stop(uv_signal_t* handle);
/*
* Gets load average.
*
* See: http://en.wikipedia.org/wiki/Load_(computing)
*
* Returns [0,0,0] on Windows.
*/
UV_EXTERN void uv_loadavg(double avg[3]);
/*
* Flags to be passed to uv_fs_event_start.
* Flags to be passed to uv_fs_event_start().
*/
enum uv_fs_event_flags {
/*
@ -2116,32 +2133,34 @@ UV_EXTERN int uv_fs_event_getpath(uv_fs_event_t* handle,
size_t* len);
/* Utility */
/* Utilities. */
/* Convert string ip addresses to binary structures */
/* Convert string ip addresses to binary structures. */
UV_EXTERN int uv_ip4_addr(const char* ip, int port, struct sockaddr_in* addr);
UV_EXTERN int uv_ip6_addr(const char* ip, int port, struct sockaddr_in6* addr);
/* Convert binary addresses to strings */
/* Convert binary addresses to strings. */
UV_EXTERN int uv_ip4_name(const struct sockaddr_in* src, char* dst, size_t size);
UV_EXTERN int uv_ip6_name(const struct sockaddr_in6* src, char* dst, size_t size);
/* Cross-platform IPv6-capable implementation of the 'standard' inet_ntop */
/* and inet_pton functions. On success they return 0. If an error */
/* the target of the `dst` pointer is unmodified. */
/*
* Cross-platform IPv6-capable implementation of the 'standard' inet_ntop() and
* inet_pton() functions. On success they return 0. If an error the target of
* the `dst` pointer is unmodified.
*/
UV_EXTERN int uv_inet_ntop(int af, const void* src, char* dst, size_t size);
UV_EXTERN int uv_inet_pton(int af, const char* src, void* dst);
/* Gets the executable path */
/* Gets the executable path. */
UV_EXTERN int uv_exepath(char* buffer, size_t* size);
/* Gets the current working directory */
/* Gets the current working directory. */
UV_EXTERN int uv_cwd(char* buffer, size_t* size);
/* Changes the current working directory */
/* Changes the current working directory. */
UV_EXTERN int uv_chdir(const char* dir);
/* Gets memory info in bytes */
/* Gets memory info in bytes. */
UV_EXTERN uint64_t uv_get_free_memory(void);
UV_EXTERN uint64_t uv_get_total_memory(void);
@ -2167,13 +2186,13 @@ UV_EXTERN extern uint64_t uv_hrtime(void);
*
* Note that this function works on a best-effort basis: there is no guarantee
* that libuv can discover all file descriptors that were inherited. In general
* it does a better job on Windows than it does on unix.
* it does a better job on Windows than it does on Unix.
*/
UV_EXTERN void uv_disable_stdio_inheritance(void);
/*
* Opens a shared library. The filename is in utf-8. Returns 0 on success and
* -1 on error. Call `uv_dlerror(uv_lib_t*)` to get the error message.
* -1 on error. Call uv_dlerror(uv_lib_t*) to get the error message.
*/
UV_EXTERN int uv_dlopen(const char* filename, uv_lib_t* lib);
@ -2194,8 +2213,8 @@ UV_EXTERN int uv_dlsym(uv_lib_t* lib, const char* name, void** ptr);
UV_EXTERN const char* uv_dlerror(const uv_lib_t* lib);
/*
* The mutex functions return 0 on success or an error code < 0
* (unless the return type is void, of course).
* The mutex functions return 0 on success or an error code < 0 (unless the
* return type is void, of course).
*/
UV_EXTERN int uv_mutex_init(uv_mutex_t* handle);
UV_EXTERN void uv_mutex_destroy(uv_mutex_t* handle);
@ -2244,31 +2263,35 @@ UV_EXTERN int uv_barrier_init(uv_barrier_t* barrier, unsigned int count);
UV_EXTERN void uv_barrier_destroy(uv_barrier_t* barrier);
UV_EXTERN int uv_barrier_wait(uv_barrier_t* barrier);
/* Waits on a condition variable without a timeout.
/*
* Waits on a condition variable without a timeout.
*
* Note:
* 1. callers should be prepared to deal with spurious wakeups.
* NOTE:
* 1. callers should be prepared to deal with spurious wakeups.
*/
UV_EXTERN void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex);
/* Waits on a condition variable with a timeout in nano seconds.
/*
* Waits on a condition variable with a timeout in nano seconds.
* Returns 0 for success or UV_ETIMEDOUT on timeout, It aborts when other
* errors happen.
*
* Note:
* 1. callers should be prepared to deal with spurious wakeups.
* 2. the granularity of timeout on Windows is never less than one millisecond.
* 3. uv_cond_timedwait takes a relative timeout, not an absolute time.
* NOTE:
* 1. callers should be prepared to deal with spurious wakeups.
* 2. the granularity of timeout on Windows is never less than one millisecond.
* 3. uv_cond_timedwait() takes a relative timeout, not an absolute time.
*/
UV_EXTERN int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex,
uint64_t timeout);
/* Runs a function once and only once. Concurrent calls to uv_once() with the
/*
* Runs a function once and only once. Concurrent calls to uv_once() with the
* same guard will block all callers except one (it's unspecified which one).
* The guard should be initialized statically with the UV_ONCE_INIT macro.
*/
UV_EXTERN void uv_once(uv_once_t* guard, void (*callback)(void));
/* Thread-local storage. These functions largely follow the semantics of
/*
* Thread-local storage. These functions largely follow the semantics of
* pthread_key_create(), pthread_key_delete(), pthread_getspecific() and
* pthread_setspecific().
*
@ -2306,11 +2329,11 @@ union uv_any_req {
struct uv_loop_s {
/* User data - use this for whatever. */
void* data;
/* Loop reference counting */
/* Loop reference counting. */
unsigned int active_handles;
void* handle_queue[2];
void* active_reqs[2];
/* Internal flag to signal loop stop */
/* Internal flag to signal loop stop. */
unsigned int stop_flag;
UV_LOOP_PRIVATE_FIELDS
};