lep: request all the things

XXX-request-all-the-things.md

@@ -0,0 +1,210 @@
+| Title  | Request all the things  |
+|--------|-------------------------|
+| Author | @saghul                 |
+| Status | DRAFT                   |
+| Date   | 2014-11-27 07:43:59     |
+
+
+## Overview
+
+This proposal describes a new approach for dealing with operations in libuv. As of
+right now, handles define an entity which is capable of performing certain operations.
+These operations are sometimes a result of a request being sent and some other times a
+result of a callback (which was passed by the user) being called. This proposal aims
+to make this behavior more consistent, by turning several operations that currently
+just take a callback into a request form.
+
+
+### uv_read
+
+(This was previously discussed, but it’s added here for completeness).
+
+Instead of using a callback passed to `uv_read_start`, the plan is to use a `uv_read`
+function which performs a single read operation. The initial prototype was defined
+as follows:
+
+~~~~
+int uv_read(uv_read_t* req,
+            uv_stream_t* handle,
+            const uv_buf_t[] bufs,
+            unsigned int nbufs,
+            uv_read_cb, cb)
+~~~~
+
+The read callback is defined as:
+
+~~~~
+typedef void (*uv_read_cb)(uv_read_t* req, int status)
+~~~~
+
+This approach has one problem, though: memory for reading needs to be allocated upfront,
+which might not be desirable in all cases. For this reason, a secondary version which takes
+an allocation callback is also proposed:
+
+~~~~
+int uv_read_alloc(uv_read_t* req,
+                  uv_stream_t* handle,
+                  uv_alloc_cb alloc_cb,
+                  uv_read_cb cb)
+~~~~
+
+Applications can use one or the other or mixed without problems.
+
+Implementation details: we probably will want to have some `bufsml` of size 4 where we
+copy the structures when the request is created, like `uv_write` does. Thus, the user can
+pass a `uv_buf_t` array which is allocated on the stack, as long as the memory in each `buf->base`
+is valid until the request callback is called.
+
+Inline reading: if there are no conditions which would prevent otherwise, we could try to do
+a read on the spot. This should work ok if the user provided preallocated buffers, because
+we can hold on to them if we get EAGAIN. If `uv_read_alloc` is used, instead, we won’t attempt
+to read on the spot because the allocation callback would have to be called and we’d end
+up holding on to the buffer for too long, thus defeating the purpose of deferred allocation.
+A best effort inline reading function is also proposed:
+
+~~~~
+int uv_try_read(uv_stream_t* handle,
+                const uv_buf_t[] bufs,
+                unsigned int nbufs)
+~~~~
+
+It does basically the analogous to `uv_try_write`, that is, attempt to read inline and
+doesn’t queue a request if it doesn’t succeed.
+
+### uv_stream_poll
+
+In case `uv_read` and `uv_read_alloc` are not enough, another way to read or write on streams
+would be to get a callback when the stream is readable / writable, and use the `uv_try_*`
+family of functions to perform the reads and writes inline. The proposed API for this:
+
+~~~~
+int uv_stream_poll(uv_stream_poll_t* req,
+                   uv_stream_t* handle,
+                   int events,
+                   uv_stream_poll cb)
+~~~~
+
+`events` would be a mask composed of `UV_READABLE` and / or `UV_WRITABLE`.
+
+The callback is defined as:
+
+~~~~
+typedef void (*uv_stream_poll_cb)(uv_stream_poll_t* req, int status)
+~~~~
+
+
+### uv_timeout
+
+Currently libuv implements repeating timers in the form of a handle. The current implementation
+does not account for the time taken during the callback, and this has caused some trouble
+every now and then, since people have different expectations when it comes to repeating timers.
+
+This proposal removes the timer handle and makes timers a request, which gets its callback
+called when the timeout is hit:
+
+~~~~
+int uv_timeout(uv_timeout_t* req,
+               uv_loop_t* loop,
+               double timeout,
+               uv_timeout_cb cb)
+~~~~
+
+The `timeout` is now expressed as a double. The fractional part will get rounded up
+to platform granularity. For example: 1.2345 becomes 1230 ms or 1,234,500 us,
+depending on whether the platform supports sub-millisecond precision.
+
+Timers are one shot, so no assumptions are made and repeating timers can be easily
+implemented on top (by users).
+
+The callback takes the following form:
+
+~~~~
+typedef void (*uv_timeout_cb)(uv_timeout_t* req, int status)
+~~~~
+
+The status argument would indicate success or failure. One possible failure is cancellation,
+which would make status == `UV_ECANCELED`.
+
+Implementation detail: Timers will be the first thing to be processed after polling for i/o.
+
+
+### uv_callback
+
+In certain environments users would like to get a callback called by the event loop, but
+scheduling this callback would happen from a different thread. This can be implemented using
+`uv_async_t` handles in combination with some sort of thread safe queue, but it’s not
+straightforward. Also, many have fallen in the trap of `uv_async_send` coalescing calls,
+that is, calling the function X times does not yield the callback being called X times; it’s
+called at least once.
+
+`uv_callback` requests will queue the given callback, so that it’s called “as soon as
+possible” by the event loop. 2 API calls are provided, in order to make the thread-safe
+version explicit:
+
+~~~~
+int uv_callback(uv_callback_t* req, uv_loop_t* loop, uv_callback_cb cb)
+int uv_callback_threadsafe(uv_callback_t* req, uv_loop_t* loop, uv_callback_cb cb)
+~~~~
+
+The callback definition:
+
+~~~~
+typedef void (*uv_callback_cb)(uv_callback_t* req, int status)
+~~~~
+
+Implementation detail: since the callback request cannot be safely initialized outside
+of the loop thread, when `uv_callback_threadsafe` is used, the request will be put
+in a queue which will be processed by the loop at some point, fully initializing the
+requests.
+
+The introduction of `uv_callback` would deprecate and remove `uv_async_t` handles.
+Now, in some cases it might be desired to just wake up the event loop, and having to
+create a request might be too much, thus, the following API call is also proposed:
+
+~~~~
+void uv_loop_wakeup(uv_loop_t* loop)
+~~~~
+
+Which would just wake up the event loop in case it was blocked waiting for i/o.
+
+Implementation detail: the underlying mechanism for waking up the loop will be decided
+later on. The current `uv_async_t` machanism could remain (on Unix) or atomic ops
+could be used instead.
+
+Note: As a result of this addition, `uv_idle_t` handles will be deprecated an removed.
+It may not seem obvious at first, but `uv_callback` achieves the same: the loop won’t block
+for i/o if any `uv_callback` request is pending. This becomes even more obvious with the
+“‘pull based’ event loop” proposal.
+
+
+### uv_accept / uv_listen
+
+Currently there is no way to stop listening for incoming connections. Making the concept
+of accepting connections also request based makes the API more consistent and easier
+to use: if the user decides so (maybe because she is getting EMFILE because she ran
+out of file descriptors, for example) she can stop accepting new connections.
+
+New API:
+
+~~~~
+int uv_listen(uv_stream_t* stream, int backlog)
+~~~~
+
+The uv_listen function loses its callback, becoming the equivalent of `listen(2)`.
+
+~~~~
+int uv_accept(uv_accept_t* req, uv_stream_t* stream, uv_accept_cb cb)
+typedef void (*uv_accept_cb)(uv_accept_t* req, int status)
+~~~~
+
+Once a connection is accepted the request callback will be called with status == 0.
+The `req->fd` field will contain a `uv_os_fd_t` value, which the user can use together
+with `uv_tcp_open` for example. (This needs further investigation to verify it would
+work in all cases).
+
+
+### A note on uv_cancel
+
+Gradually, `uv_cancel` needs to be improved to allow for cancelling any kind of requests.
+Some of them might be a bit harder, but `uv_timeout` and `uv_callback` should be easy
+enough to do.