diff options
| -rw-r--r-- | docs/implementation-guide.md | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/docs/implementation-guide.md b/docs/implementation-guide.md new file mode 100644 index 0000000..9393bdc --- /dev/null +++ b/docs/implementation-guide.md @@ -0,0 +1,57 @@ +# Implementation Guide + +`uv_link_t` behaves very similar to [`uv_stream_t`][0]. All `uv_link_methods_t` +MUST conform to this semantics. + +## uv_link_init() + +Links start in non-reading mode, `alloc_cb`/`read_cb` MUST NOT be called until +`uv_link_read_start(link)` will be invoked with zero return code. + +## uv_link_read_start()/uv_link_read_stop() + +This switch link to and from the reading mode. After the switch to the reading +mode either: + +* `alloc_cb` + `read_cb` will be invoked for a particular link (NOTE: `read_cb` + MUST follow every `alloc_cb`) +* `read_cb(..., err, ...)` will be called to indicate a error. In this case user + MUST call `uv_read_stop()` on the error'ed link. + +NOTE: `buf` argument of `read_cb` may be `NULL` in case of error. + +NOTE: If `alloc_cb` sets `buf->len = 0;` - `read_cb(..., UV_ENOBUFS, ...)` MUST +be called by a link implementation. + +## uv_link_close() + +Links MAY be closed at any time, unless they are already closed or weren't +initialized with `uv_link_init()`. However, the `methods->close()` may not be +called immediately on `uv_link_close()` if close attempt is happening on the +link's call stack: + +```c +static void read_cb(uv_link_t* link, ssize_t nread, uv_buf_t* buf) { + uv_link_close(link, ...); +} + +link->read_cb = read_cb; + +uv_link_propagate_read_cb(link, UV_EOF, NULL); +/* link->methods->close() call will happen upon returning from + `uv_link_propagate_read_cb` */ +``` + +uv_link_t public APIs MUST NOT be used on a link after `uv_link_close(link)`. + +When several links are chained together, `uv_link_close()` SHOULD be called only +on a last (leaf) link in a chain. Otherwise `uv_link_t` API is allowed to crash. + +When closing leaf link in a chain: + +1. All links will be unchained +2. Each link starting from the deepest link (from the leaf) will be closed one + by one +3. `close_cb` will be invoked upon close of all links in a chain + +[0]: http://docs.libuv.org/en/v1.x/stream.html |