summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/libuv/docs/src/migration_010_100.rst
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/libuv/docs/src/migration_010_100.rst')
-rw-r--r--3rdparty/libuv/docs/src/migration_010_100.rst244
1 files changed, 0 insertions, 244 deletions
diff --git a/3rdparty/libuv/docs/src/migration_010_100.rst b/3rdparty/libuv/docs/src/migration_010_100.rst
deleted file mode 100644
index bb6ac1a8092..00000000000
--- a/3rdparty/libuv/docs/src/migration_010_100.rst
+++ /dev/null
@@ -1,244 +0,0 @@
-
-.. _migration_010_100:
-
-libuv 0.10 -> 1.0.0 migration guide
-===================================
-
-Some APIs changed quite a bit throughout the 1.0.0 development process. Here
-is a migration guide for the most significant changes that happened after 0.10
-was released.
-
-
-Loop initialization and closing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In libuv 0.10 (and previous versions), loops were created with `uv_loop_new`, which
-allocated memory for a new loop and initialized it; and destroyed with `uv_loop_delete`,
-which destroyed the loop and freed the memory. Starting with 1.0, those are deprecated
-and the user is responsible for allocating the memory and then initializing the loop.
-
-libuv 0.10
-
-::
-
- uv_loop_t* loop = uv_loop_new();
- ...
- uv_loop_delete(loop);
-
-libuv 1.0
-
-::
-
- uv_loop_t* loop = malloc(sizeof *loop);
- uv_loop_init(loop);
- ...
- uv_loop_close(loop);
- free(loop);
-
-.. note::
- Error handling was omitted for brevity. Check the documentation for :c:func:`uv_loop_init`
- and :c:func:`uv_loop_close`.
-
-
-Error handling
-~~~~~~~~~~~~~~
-
-Error handling had a major overhaul in libuv 1.0. In general, functions and status parameters
-would get 0 for success and -1 for failure on libuv 0.10, and the user had to use `uv_last_error`
-to fetch the error code, which was a positive number.
-
-In 1.0, functions and status parameters contain the actual error code, which is 0 for success, or
-a negative number in case of error.
-
-libuv 0.10
-
-::
-
- ... assume 'server' is a TCP server which is already listening
- r = uv_listen((uv_stream_t*) server, 511, NULL);
- if (r == -1) {
- uv_err_t err = uv_last_error(uv_default_loop());
- /* err.code contains UV_EADDRINUSE */
- }
-
-libuv 1.0
-
-::
-
- ... assume 'server' is a TCP server which is already listening
- r = uv_listen((uv_stream_t*) server, 511, NULL);
- if (r < 0) {
- /* r contains UV_EADDRINUSE */
- }
-
-
-Threadpool changes
-~~~~~~~~~~~~~~~~~~
-
-In libuv 0.10 Unix used a threadpool which defaulted to 4 threads, while Windows used the
-`QueueUserWorkItem` API, which uses a Windows internal threadpool, which defaults to 512
-threads per process.
-
-In 1.0, we unified both implementations, so Windows now uses the same implementation Unix
-does. The threadpool size can be set by exporting the ``UV_THREADPOOL_SIZE`` environment
-variable. See :c:ref:`threadpool`.
-
-
-Allocation callback API change
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In libuv 0.10 the callback had to return a filled :c:type:`uv_buf_t` by value:
-
-::
-
- uv_buf_t alloc_cb(uv_handle_t* handle, size_t size) {
- return uv_buf_init(malloc(size), size);
- }
-
-In libuv 1.0 a pointer to a buffer is passed to the callback, which the user
-needs to fill:
-
-::
-
- void alloc_cb(uv_handle_t* handle, size_t size, uv_buf_t* buf) {
- buf->base = malloc(size);
- buf->len = size;
- }
-
-
-Unification of IPv4 / IPv6 APIs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-libuv 1.0 unified the IPv4 and IPv6 APIS. There is no longer a `uv_tcp_bind` and `uv_tcp_bind6`
-duality, there is only :c:func:`uv_tcp_bind` now.
-
-IPv4 functions took ``struct sockaddr_in`` structures by value, and IPv6 functions took
-``struct sockaddr_in6``. Now functions take a ``struct sockaddr*`` (note it's a pointer).
-It can be stack allocated.
-
-libuv 0.10
-
-::
-
- struct sockaddr_in addr = uv_ip4_addr("0.0.0.0", 1234);
- ...
- uv_tcp_bind(&server, addr)
-
-libuv 1.0
-
-::
-
- struct sockaddr_in addr;
- uv_ip4_addr("0.0.0.0", 1234, &addr)
- ...
- uv_tcp_bind(&server, (const struct sockaddr*) &addr, 0);
-
-The IPv4 and IPv6 struct creating functions (:c:func:`uv_ip4_addr` and :c:func:`uv_ip6_addr`)
-have also changed, make sure you check the documentation.
-
-..note::
- This change applies to all functions that made a distinction between IPv4 and IPv6
- addresses.
-
-
-Streams / UDP data receive callback API change
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The streams and UDP data receive callbacks now get a pointer to a :c:type:`uv_buf_t` buffer,
-not a structure by value.
-
-libuv 0.10
-
-::
-
- void on_read(uv_stream_t* handle,
- ssize_t nread,
- uv_buf_t buf) {
- ...
- }
-
- void recv_cb(uv_udp_t* handle,
- ssize_t nread,
- uv_buf_t buf,
- struct sockaddr* addr,
- unsigned flags) {
- ...
- }
-
-libuv 1.0
-
-::
-
- void on_read(uv_stream_t* handle,
- ssize_t nread,
- const uv_buf_t* buf) {
- ...
- }
-
- void recv_cb(uv_udp_t* handle,
- ssize_t nread,
- const uv_buf_t* buf,
- const struct sockaddr* addr,
- unsigned flags) {
- ...
- }
-
-
-Receiving handles over pipes API change
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In libuv 0.10 (and earlier versions) the `uv_read2_start` function was used to start reading
-data on a pipe, which could also result in the reception of handles over it. The callback
-for such function looked like this:
-
-::
-
- void on_read(uv_pipe_t* pipe,
- ssize_t nread,
- uv_buf_t buf,
- uv_handle_type pending) {
- ...
- }
-
-In libuv 1.0, `uv_read2_start` was removed, and the user needs to check if there are pending
-handles using :c:func:`uv_pipe_pending_count` and :c:func:`uv_pipe_pending_type` while in
-the read callback:
-
-::
-
- void on_read(uv_stream_t* handle,
- ssize_t nread,
- const uv_buf_t* buf) {
- ...
- while (uv_pipe_pending_count((uv_pipe_t*) handle) != 0) {
- pending = uv_pipe_pending_type((uv_pipe_t*) handle);
- ...
- }
- ...
- }
-
-
-Extracting the file descriptor out of a handle
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-While it wasn't supported by the API, users often accessed the libuv internals in
-order to get access to the file descriptor of a TCP handle, for example.
-
-::
-
- fd = handle->io_watcher.fd;
-
-This is now properly exposed through the :c:func:`uv_fileno` function.
-
-
-uv_fs_readdir rename and API change
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-`uv_fs_readdir` returned a list of strings in the `req->ptr` field upon completion in
-libuv 0.10. In 1.0, this function got renamed to :c:func:`uv_fs_scandir`, since it's
-actually implemented using ``scandir(3)``.
-
-In addition, instead of allocating a full list strings, the user is able to get one
-result at a time by using the :c:func:`uv_fs_scandir_next` function. This function
-does not need to make a roundtrip to the threadpool, because libuv will keep the
-list of *dents* returned by ``scandir(3)`` around.