From 18f54bef3130d640887cc15a01b1f0cee0af42cb Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Sat, 28 May 2011 01:47:47 -0700 Subject: [PATCH] Add doc on desired-api --- README | 15 +------------- desired-api.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 14 deletions(-) create mode 100644 desired-api.md diff --git a/README b/README index 38bb8a68..4e2c2cd2 100644 --- a/README +++ b/README @@ -6,7 +6,7 @@ http://nodejs.org/ (This was previously called liboio) -## Supported Platforms +Supported Platforms: Microsoft Windows operating systems since Windows XP sp2. It can be built with either Visual Studio or MinGW. @@ -14,16 +14,3 @@ with either Visual Studio or MinGW. Linux 2.6 and MacOS using the GCC toolchain. Solaris 121 and later using GCC toolchain. - -## Design - -The goal of this library is to provide high-concurrency high-performance I/O -on all operating systems. This is a large undertaking. Some of the API -decisions may seem arbitrary but are actually borne out of various specific -platform issues. - -## uv_read_start(), uv_read_stop() - -Originally we wanted to provide a asynchronous read function that was -similar to WSARecv(). - diff --git a/desired-api.md b/desired-api.md new file mode 100644 index 00000000..78beab1f --- /dev/null +++ b/desired-api.md @@ -0,0 +1,55 @@ +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. + + +# `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);` + + +# `uv_tcp_t` + +The TCP handle class abstracts one endpoint of a duplex TCP stream or a listening socket. `uv_tcp_t` is a subclass of `uv_stream_t`. + +TCP stream's fundamental operations are reading and writing data. Additionally duplex TCP streams can be half-closed. Either