luo980/libuv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add doc on desired-api

Browse Source
This commit is contained in:
Ryan Dahl 2011-05-28 01:47:47 -07:00
parent be1bfe6c4c
commit 18f54bef31
2 changed files with 56 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
README
View File

@ -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().

55
desired-api.md Normal file
View File

@ -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