|
160
|
1
|
|
|
2 .. _migration_010_100:
|
|
|
3
|
|
|
4 libuv 0.10 -> 1.0.0 migration guide
|
|
|
5 ===================================
|
|
|
6
|
|
|
7 Some APIs changed quite a bit throughout the 1.0.0 development process. Here
|
|
|
8 is a migration guide for the most significant changes that happened after 0.10
|
|
|
9 was released.
|
|
|
10
|
|
|
11
|
|
|
12 Loop initialization and closing
|
|
|
13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
14
|
|
|
15 In libuv 0.10 (and previous versions), loops were created with `uv_loop_new`, which
|
|
|
16 allocated memory for a new loop and initialized it; and destroyed with `uv_loop_delete`,
|
|
|
17 which destroyed the loop and freed the memory. Starting with 1.0, those are deprecated
|
|
|
18 and the user is responsible for allocating the memory and then initializing the loop.
|
|
|
19
|
|
|
20 libuv 0.10
|
|
|
21
|
|
|
22 ::
|
|
|
23
|
|
|
24 uv_loop_t* loop = uv_loop_new();
|
|
|
25 ...
|
|
|
26 uv_loop_delete(loop);
|
|
|
27
|
|
|
28 libuv 1.0
|
|
|
29
|
|
|
30 ::
|
|
|
31
|
|
|
32 uv_loop_t* loop = malloc(sizeof *loop);
|
|
|
33 uv_loop_init(loop);
|
|
|
34 ...
|
|
|
35 uv_loop_close(loop);
|
|
|
36 free(loop);
|
|
|
37
|
|
|
38 .. note::
|
|
|
39 Error handling was omitted for brevity. Check the documentation for :c:func:`uv_loop_init`
|
|
|
40 and :c:func:`uv_loop_close`.
|
|
|
41
|
|
|
42
|
|
|
43 Error handling
|
|
|
44 ~~~~~~~~~~~~~~
|
|
|
45
|
|
|
46 Error handling had a major overhaul in libuv 1.0. In general, functions and status parameters
|
|
|
47 would get 0 for success and -1 for failure on libuv 0.10, and the user had to use `uv_last_error`
|
|
|
48 to fetch the error code, which was a positive number.
|
|
|
49
|
|
|
50 In 1.0, functions and status parameters contain the actual error code, which is 0 for success, or
|
|
|
51 a negative number in case of error.
|
|
|
52
|
|
|
53 libuv 0.10
|
|
|
54
|
|
|
55 ::
|
|
|
56
|
|
|
57 ... assume 'server' is a TCP server which is already listening
|
|
|
58 r = uv_listen((uv_stream_t*) server, 511, NULL);
|
|
|
59 if (r == -1) {
|
|
|
60 uv_err_t err = uv_last_error(uv_default_loop());
|
|
|
61 /* err.code contains UV_EADDRINUSE */
|
|
|
62 }
|
|
|
63
|
|
|
64 libuv 1.0
|
|
|
65
|
|
|
66 ::
|
|
|
67
|
|
|
68 ... assume 'server' is a TCP server which is already listening
|
|
|
69 r = uv_listen((uv_stream_t*) server, 511, NULL);
|
|
|
70 if (r < 0) {
|
|
|
71 /* r contains UV_EADDRINUSE */
|
|
|
72 }
|
|
|
73
|
|
|
74
|
|
|
75 Threadpool changes
|
|
|
76 ~~~~~~~~~~~~~~~~~~
|
|
|
77
|
|
|
78 In libuv 0.10 Unix used a threadpool which defaulted to 4 threads, while Windows used the
|
|
|
79 `QueueUserWorkItem` API, which uses a Windows internal threadpool, which defaults to 512
|
|
|
80 threads per process.
|
|
|
81
|
|
|
82 In 1.0, we unified both implementations, so Windows now uses the same implementation Unix
|
|
|
83 does. The threadpool size can be set by exporting the ``UV_THREADPOOL_SIZE`` environment
|
|
|
84 variable. See :c:ref:`threadpool`.
|
|
|
85
|
|
|
86
|
|
|
87 Allocation callback API change
|
|
|
88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
89
|
|
|
90 In libuv 0.10 the callback had to return a filled :c:type:`uv_buf_t` by value:
|
|
|
91
|
|
|
92 ::
|
|
|
93
|
|
|
94 uv_buf_t alloc_cb(uv_handle_t* handle, size_t size) {
|
|
|
95 return uv_buf_init(malloc(size), size);
|
|
|
96 }
|
|
|
97
|
|
|
98 In libuv 1.0 a pointer to a buffer is passed to the callback, which the user
|
|
|
99 needs to fill:
|
|
|
100
|
|
|
101 ::
|
|
|
102
|
|
|
103 void alloc_cb(uv_handle_t* handle, size_t size, uv_buf_t* buf) {
|
|
|
104 buf->base = malloc(size);
|
|
|
105 buf->len = size;
|
|
|
106 }
|
|
|
107
|
|
|
108
|
|
|
109 Unification of IPv4 / IPv6 APIs
|
|
|
110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
111
|
|
|
112 libuv 1.0 unified the IPv4 and IPv6 APIS. There is no longer a `uv_tcp_bind` and `uv_tcp_bind6`
|
|
|
113 duality, there is only :c:func:`uv_tcp_bind` now.
|
|
|
114
|
|
|
115 IPv4 functions took ``struct sockaddr_in`` structures by value, and IPv6 functions took
|
|
|
116 ``struct sockaddr_in6``. Now functions take a ``struct sockaddr*`` (note it's a pointer).
|
|
|
117 It can be stack allocated.
|
|
|
118
|
|
|
119 libuv 0.10
|
|
|
120
|
|
|
121 ::
|
|
|
122
|
|
|
123 struct sockaddr_in addr = uv_ip4_addr("0.0.0.0", 1234);
|
|
|
124 ...
|
|
|
125 uv_tcp_bind(&server, addr)
|
|
|
126
|
|
|
127 libuv 1.0
|
|
|
128
|
|
|
129 ::
|
|
|
130
|
|
|
131 struct sockaddr_in addr;
|
|
|
132 uv_ip4_addr("0.0.0.0", 1234, &addr)
|
|
|
133 ...
|
|
|
134 uv_tcp_bind(&server, (const struct sockaddr*) &addr, 0);
|
|
|
135
|
|
|
136 The IPv4 and IPv6 struct creating functions (:c:func:`uv_ip4_addr` and :c:func:`uv_ip6_addr`)
|
|
|
137 have also changed, make sure you check the documentation.
|
|
|
138
|
|
|
139 ..note::
|
|
|
140 This change applies to all functions that made a distinction between IPv4 and IPv6
|
|
|
141 addresses.
|
|
|
142
|
|
|
143
|
|
|
144 Streams / UDP data receive callback API change
|
|
|
145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
146
|
|
|
147 The streams and UDP data receive callbacks now get a pointer to a :c:type:`uv_buf_t` buffer,
|
|
|
148 not a structure by value.
|
|
|
149
|
|
|
150 libuv 0.10
|
|
|
151
|
|
|
152 ::
|
|
|
153
|
|
|
154 void on_read(uv_stream_t* handle,
|
|
|
155 ssize_t nread,
|
|
|
156 uv_buf_t buf) {
|
|
|
157 ...
|
|
|
158 }
|
|
|
159
|
|
|
160 void recv_cb(uv_udp_t* handle,
|
|
|
161 ssize_t nread,
|
|
|
162 uv_buf_t buf,
|
|
|
163 struct sockaddr* addr,
|
|
|
164 unsigned flags) {
|
|
|
165 ...
|
|
|
166 }
|
|
|
167
|
|
|
168 libuv 1.0
|
|
|
169
|
|
|
170 ::
|
|
|
171
|
|
|
172 void on_read(uv_stream_t* handle,
|
|
|
173 ssize_t nread,
|
|
|
174 const uv_buf_t* buf) {
|
|
|
175 ...
|
|
|
176 }
|
|
|
177
|
|
|
178 void recv_cb(uv_udp_t* handle,
|
|
|
179 ssize_t nread,
|
|
|
180 const uv_buf_t* buf,
|
|
|
181 const struct sockaddr* addr,
|
|
|
182 unsigned flags) {
|
|
|
183 ...
|
|
|
184 }
|
|
|
185
|
|
|
186
|
|
|
187 Receiving handles over pipes API change
|
|
|
188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
189
|
|
|
190 In libuv 0.10 (and earlier versions) the `uv_read2_start` function was used to start reading
|
|
|
191 data on a pipe, which could also result in the reception of handles over it. The callback
|
|
|
192 for such function looked like this:
|
|
|
193
|
|
|
194 ::
|
|
|
195
|
|
|
196 void on_read(uv_pipe_t* pipe,
|
|
|
197 ssize_t nread,
|
|
|
198 uv_buf_t buf,
|
|
|
199 uv_handle_type pending) {
|
|
|
200 ...
|
|
|
201 }
|
|
|
202
|
|
|
203 In libuv 1.0, `uv_read2_start` was removed, and the user needs to check if there are pending
|
|
|
204 handles using :c:func:`uv_pipe_pending_count` and :c:func:`uv_pipe_pending_type` while in
|
|
|
205 the read callback:
|
|
|
206
|
|
|
207 ::
|
|
|
208
|
|
|
209 void on_read(uv_stream_t* handle,
|
|
|
210 ssize_t nread,
|
|
|
211 const uv_buf_t* buf) {
|
|
|
212 ...
|
|
|
213 while (uv_pipe_pending_count((uv_pipe_t*) handle) != 0) {
|
|
|
214 pending = uv_pipe_pending_type((uv_pipe_t*) handle);
|
|
|
215 ...
|
|
|
216 }
|
|
|
217 ...
|
|
|
218 }
|
|
|
219
|
|
|
220
|
|
|
221 Extracting the file descriptor out of a handle
|
|
|
222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
223
|
|
|
224 While it wasn't supported by the API, users often accessed the libuv internals in
|
|
|
225 order to get access to the file descriptor of a TCP handle, for example.
|
|
|
226
|
|
|
227 ::
|
|
|
228
|
|
|
229 fd = handle->io_watcher.fd;
|
|
|
230
|
|
|
231 This is now properly exposed through the :c:func:`uv_fileno` function.
|
|
|
232
|
|
|
233
|
|
|
234 uv_fs_readdir rename and API change
|
|
|
235 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
236
|
|
|
237 `uv_fs_readdir` returned a list of strings in the `req->ptr` field upon completion in
|
|
|
238 libuv 0.10. In 1.0, this function got renamed to :c:func:`uv_fs_scandir`, since it's
|
|
|
239 actually implemented using ``scandir(3)``.
|
|
|
240
|
|
|
241 In addition, instead of allocating a full list strings, the user is able to get one
|
|
|
242 result at a time by using the :c:func:`uv_fs_scandir_next` function. This function
|
|
|
243 does not need to make a roundtrip to the threadpool, because libuv will keep the
|
|
|
244 list of *dents* returned by ``scandir(3)`` around.
|
