diff --git a/doc/desired-api.md b/doc/desired-api.md deleted file mode 100644 index 9faa5759..00000000 --- a/doc/desired-api.md +++ /dev/null @@ -1,159 +0,0 @@ -Warning: this is not actual API but desired API. - -# `uv_handle_t` - -This is the abstract base class of all types of handles. All handles have in -common: - -* When handles are initialized, the reference count to the event loop is - increased by one. - -* The user owns the `uv_handle_t` memory and is in charge of freeing it. - -* In order to free resources associated with a handle, one must `uv_close()` - and wait for the `uv_close_cb` callback. After the close callback has been - made, the user is allowed to the `uv_handle_t` object. - -* The `uv_close_cb` is always made directly off the event loop. That is, it - is not called from `uv_close()`. - - - -# `uv_tcp_server_t` - -A TCP server class that is a subclass of `uv_handle_t`. This can be bound to -an address and begin accepting new TCP sockets. - - int uv_bind4(uv_tcp_server_t* tcp_server, struct sockaddr_in* address); - int uv_bind6(uv_tcp_server_t* tcp_server, struct sockaddr_in6* address); - -Binds the TCP server to an address. The `address` can be created with -`uv_ip4_addr()`. Call this before `uv_listen()` - -Returns zero on success, -1 on failure. Errors in order of least-seriousness: - -* `UV_EADDRINUSE` There is already another socket bound to the specified - address. - -* `UV_EADDRNOTAVAIL` The `address` parameter is an IP address that is not - -* `UV_EINVAL` The server is already bound to an address. - -* `UV_EFAULT` Memory of `address` parameter is unintelligible. - - - int uv_listen(uv_tcp_server_t*, int backlog, uv_connection_cb cb); - -Begins listening for connections. The accept callback is level-triggered. - - - int uv_accept(uv_tcp_server_t* server, - uv_tcp_t* client); - -Accepts a connection. This should be called after the accept callback is -made. The `client` parameter should be uninitialized memory; `uv_accept` is -used instead of `uv_tcp_init` for server-side `uv_tcp_t` initialization. - -Return value 0 indicates success, -1 failure. Possible errors: - -* `UV_EAGAIN` There are no connections. Wait for the `uv_connection_cb` callback - to be called again. - -* `UV_EFAULT` The memory of either `server` is unintelligible. - - - -# `uv_stream_t` - -An abstract subclass of `uv_handle_t`. Streams represent something that -reads and/or writes data. Streams can be half or full-duplex. TCP sockets -are streams, files are streams with offsets. - - int uv_read_start(uv_stream_t* stream, - uv_alloc_cb alloc_cb, - uv_read_cb read_cb); - -Starts the stream reading continuously. The `alloc_cb` is used to allow the -user to implement various means of supplying the stream with buffers to -fill. The `read_cb` returns buffers to the user filled with data. - -Sometimes the buffers returned to the user do not contain data. This does -not indicate EOF as in other systems. EOF is made via the `uv_eof_cb` which -can be set like this `uv_set_eof_cb(stream, eof_cb);` - - - int uv_read_stop(uv_stream_t* stream); - -Stops reading from the stream. - - int uv_write_req_init(uv_write_req_t*, - uv_stream_t*, - uv_buf_t bufs[], - int butcnf); - -Initiates a write request on a stream. - - int uv_shutdown_req_init(uv_shutdown_req_t*, uv_stream_t*) - -Initiates a shutdown of outgoing data once the write queue drains. - - - -# `uv_tcp_t` - -The TCP handle class represents one endpoint of a duplex TCP stream. -`uv_tcp_t` is a subclass of `uv_stream_t`. A TCP handle can represent a -client side connection (one that has been used with uv_connect_req_init`) -or a server-side connection (one that was initialized with `uv_accept`) - - int uv_connect_req_init(uv_connect_req_t* req, - uv_tcp_t* socket, - struct sockaddr* addr); - -Initiates a request to open a connection. - - - -# `uv_req_t` - -Abstract class represents an asynchronous request. This is a subclass of `uv_handle_t`. - - -# `uv_connect_req_t` - -Subclass of `uv_req_t`. Represents a request for a TCP connection. Operates -on `uv_tcp_t` handles. Like other types of requests the `close_cb` indicates -completion of the request. - - int uv_connect_req_init(uv_connect_req_t* req, - uv_tcp_t* socket, - struct sockaddr* addr); - -Initializes the connection request. Returning 0 indicates success, -1 if -there was an error. The following values can be retrieved from -`uv_last_error` in the case of an error: - -* ??? - - -# `uv_shutdown_req_t` - -Subclass of `uv_req_t`. Represents an ongoing shutdown request. Once the -write queue of the parent `uv_stream_t` is drained, the outbound data -channel is shutdown. Once a shutdown request is initiated on a stream, the -stream will allow no more writes. - - int uv_shutdown_req_init(uv_shutdown_req_t*, - uv_stream_t* parent); - -Initializes the shutdown request. - - -# `uv_write_req_t` - - int uv_write_req_init(uv_write_req_t*, - uv_stream_t*, - uv_buf_t bufs[], - int butcnf); - -Initiates a write request on a stream.