diff options
| -rw-r--r-- | docs/api.md | 211 | ||||
| -rw-r--r-- | src/uv_link_t.c | 6 |
2 files changed, 205 insertions, 12 deletions
diff --git a/docs/api.md b/docs/api.md index 75ab5c1..ae78846 100644 --- a/docs/api.md +++ b/docs/api.md @@ -10,6 +10,9 @@ specified otherwise. The base unit of all APIs. Pointer to this structure is what needs to be passed to the most of the methods. +*NOTE: please don't call methods from [method table][] directly. There are +plenty of API methods that wrap this calls in a simpler and portable manner.* + ### int uv_link_init(...) * `uv_link_t* link` - user allocated `uv_link_t` instance @@ -27,7 +30,7 @@ used in any other APIs. * `uv_link_close_cb cb` - callback to be invoked upon close Close `uv_link_t` instance and all other `uv_link_t`s chained into it (see -[uv_link_chain][]), invoke `void (*cb)(uv_link_t*)` once done (may happen +[uv_link_chain()][]), invoke `void (*cb)(uv_link_t*)` once done (may happen synchronously or on a next libuv tick, depending on particular `uv_link_t` implementation). @@ -42,12 +45,12 @@ Invokes `close` from link's [method table][]. "Chain" two `uv_link_t` instances together, set `from.child = to` and `to.parent = from`. After this call, all data emitted by `from` link via -[uv_link_propagate_alloc_cb][] and [uv_link_propagate_read_cb][] will be passed -to `to` link's [method table][]'s [alloc_cb_override][] and -[read_cb_override][]. +[uv_link_propagate_alloc_cb()][] and [uv_link_propagate_read_cb()][] will be +passed to `to` link's [method table][]'s [.alloc_cb_override][] and +[.read_cb_override][]. Closing `to` with `uv_link_close` will also close `from`, unless they will be -later unchained with [uv_link_unchain][]. +later unchained with [uv_link_unchain()][]. *NOTE: Links can have at most one parent and one child.* @@ -63,14 +66,14 @@ values (that they had before `uv_link_unchain()` call). * `uv_link_t* link` -Invoke `read_start` from the link's [method table][]. [alloc_cb][]/[read_cb][] +Invoke `read_start` from the link's [method table][]. [.alloc_cb][]/[.read_cb][] may be called after successful `uv_link_read_start`. ### int uv_link_read_stop(...) * `uv_link_t* link` -Invoke `read_stop` from the link's [method table][]. [alloc_cb][]/[read_cb][] +Invoke `read_stop` from the link's [method table][]. [.alloc_cb][]/[.read_cb][] won't be called after `uv_link_read_stop`. ### int uv_link_write(...) @@ -134,32 +137,224 @@ Arguments have the same meaning as in `uv_read_cb`. When calling this function `link->read_cb` will be invoked with either `link` or `link->child` (if latter is not `NULL`). -This should be used to emit data from `uv_link_t`. Semantics are the same as of +Should be used to emit data from `uv_link_t`. Semantics are the same as of `uv_read_cb`. ### int uv_link_propagate_write(...) Should be used only by `uv_link_methods_t` implementation. +* `uv_link_t* link` +* `uv_link_t* source` - source link to be passed to `cb` as a first argument +* `const uv_buf_t bufs[]` - buffers to write +* `unsigned int nbufs` - number of buffers to write +* `uv_stream_t* send_handle` - handle to send through IPC (if supported by + underlying [uv_link_source_t][]) +* `uv_link_write_cb cb` - callback to be invoked +* `void* arg` - user data to be passed to callback + +Invoke `write` from the`link`'s [method table][]. Could be used to +pass through the data in a following way: + +```c +uv_link_propagate_write(link->parent, source, ...); +``` + +*NOTE: `source` and `cb` may be passed through multiple links to avoid storing +extra data in auxilliary structures.* + ### int uv_link_propagate_shutdown(...) Should be used only by `uv_link_methods_t` implementation. +* `uv_link_t* link` +* `uv_link_t* source` - source link to be passed to `cb` as a first argument +* `uv_link_shutdown_cb cb` - callback to be invoked +* `void* arg` - user data to be passed to callback + +Invoke `shutdown` from the`link`'s [method table][]. Could be used to +pass through shutdown request in a following way: + +```c +uv_link_propagate_shutdown(link->parent, source, ...); +``` + +*NOTE: `source` and `cb` may be passed through multiple links to avoid storing +extra data in auxilliary structures.* + ### void uv_link_propagate_close(...) Should be used only by `uv_link_methods_t` implementation. +* `uv_link_t* link` +* `uv_link_t* source` - source link to be passed to `cb` as a first argument +* `uv_link_close_cb cb` - callback to be invoked + +Invoke `close` from the`link`'s [method table][]. Could be used to +close auxiliary links that are not in a current chain. + +`source` MUST be a leaf link of chain that is currently being closed. + ### .data +```c +void* data; +``` + Property of `void*` type, any value may be stored here. Not used internally. ### .alloc_cb + +```c +typedef void (*uv_link_alloc_cb)(uv_link_t* link, + size_t suggested_size, + uv_buf_t* buf); +``` + +Invoked by [uv_link_propagate_alloc_cb()][] to emit data on `link`. +Semantics are the same as in `uv_alloc_cb`. + +By default contains a function that `malloc`s `suggested_size`. + +Overridden on [uv_link_chain()][] call by the value of `alloc_cb_override` from +the child link's [method table][]. + ### .read_cb + +```c +typedef void (*uv_link_read_cb)(uv_link_t* link, + ssize_t nread, + const uv_buf_t* buf); +``` + +Invoked by [uv_link_propagate_read_cb()][] to emit data on `link`. +Semantics are the same as in `uv_read_cb`. + +By default just `free`s the `buf->base`, if `buf` is not `NULL`. + +Overridden on [uv_link_chain()][] call by the value of `read_cb_override` from +the child link's [method table][]. + ### .parent + +```c +uv_link_t* parent; +``` + +Pointer to the parent link in a chain. Default value: `NULL`. + ### .child +```c +uv_link_t* child; +``` + +Pointer to the child link in a chain. Default value: `NULL`. + ## uv_link_methods_t +Methods table, can be shared by multiple links. In the most of the cases should +be a pointer to a static structure, since it is immutable and contains only +pointers to the functions. + +Must be provided to [uv_link_init()][]. + +### .read_start + +```c +int (*read_start)(uv_link_t* link); +``` + +Invoked by [uv_link_read_start()][]. Data may be emitted after this call. + +*NOTE: semantics are the same as of `uv_read_start`.* + +### .read_stop + +```c +int (*read_stop)(uv_link_t* link); +``` + +Invoked by [uv_link_read_stop()][]. Data MUST not be emitted after this call. + +*NOTE: semantics are the same as of `uv_read_stop`.* + +### .write + +```c +int (*write)(uv_link_t* link, + uv_link_t* source, + const uv_buf_t bufs[], + unsigned int nbufs, + uv_stream_t* send_handle, + uv_link_write_cb cb, + void* arg); +``` + +Invoked by [uv_link_write()][] or by [uv_link_propagate_write()][]. + +At the time of completion of operation `cb(source, ...)` MUST be called, `link` +is passed only only for internal operation. + +*NOTE: semantics are the same as of `uv_write2`.* + +### .try_write + +```c +int (*try_write)(uv_link_t* link, + const uv_buf_t bufs[], + unsigned int nbufs); +``` + +Invoked by [uv_link_try_write()][]. + +*NOTE: semantics are the same as of `uv_try_write`.* + +### .shutdown + +```c +int (*shutdown)(uv_link_t* link, + uv_link_t* source, + uv_link_shutdown_cb cb, + void* arg); +``` + +Invoked by [uv_link_shutdown()][] or [uv_link_propagate_shutdown][]. + +At the time of completion of operation `cb(source, ...)` MUST be called, `link` +is passed only only for internal operation. + +*NOTE: semantics are the same as of `uv_shutdown`.* + +### .close + +```c +void (*close)(uv_link_t* link, uv_link_t* source, uv_link_close_cb cb); +``` + +Invoked by [uv_link_close()][] or [uv_link_propagate_close][]. + +At the time of completion of operation `cb(source, ...)` MUST be called, `link` +is passed only only for internal operation. + +*NOTE: semantics are the same as of `uv_close`.* + +### .alloc_cb_override + +A method used to override that value of [.alloc_cb][] by [uv_link_chain()][] +call. + +*NOTE: this method will always receive a `link` associated with a +[method table][] that has this `alloc_cb_override`. This is guaranteed by API.* + +### .read_cb_override + +A method used to override that value of [.read_cb][] by [uv_link_chain()][] +call. + +*NOTE: this method will always receive a `link` associated with a +[method table][] that has this `read_cb_override`. This is guaranteed by API.* + ## uv_link_source_t ### int uv_link_source_init(...) diff --git a/src/uv_link_t.c b/src/uv_link_t.c index d63a07b..852e26e 100644 --- a/src/uv_link_t.c +++ b/src/uv_link_t.c @@ -6,10 +6,8 @@ static void uv_link_def_alloc_cb(uv_link_t* link, size_t suggested_size, uv_buf_t* buf) { - static const size_t kBufferSize = 16 * 1024; - - buf->base = malloc(kBufferSize); - buf->len = kBufferSize; + buf->base = malloc(suggested_size); + buf->len = suggested_size; CHECK_NE(buf->base, NULL, "uv_link_t: alloc_cb failure"); } |