From 6f8cae8cc2c2af3983edac7dbbc9cd8e2ed81377 Mon Sep 17 00:00:00 2001 From: Michele Caini Date: Wed, 26 Sep 2018 14:05:15 +0200 Subject: [PATCH] updated doc: v1.11.1 --- README_8md_source.html | 4 ++-- annotated.html | 2 +- async_8hpp_source.html | 2 +- check_8hpp_source.html | 2 +- classes.html | 2 +- classuvw_1_1AsyncHandle-members.html | 2 +- classuvw_1_1AsyncHandle.html | 2 +- classuvw_1_1CheckHandle-members.html | 2 +- classuvw_1_1CheckHandle.html | 2 +- classuvw_1_1Emitter-members.html | 2 +- classuvw_1_1Emitter.html | 2 +- classuvw_1_1FileReq-members.html | 2 +- classuvw_1_1FileReq.html | 2 +- classuvw_1_1Flags-members.html | 2 +- classuvw_1_1Flags.html | 2 +- classuvw_1_1FsEventHandle-members.html | 2 +- classuvw_1_1FsEventHandle.html | 2 +- classuvw_1_1FsPollHandle-members.html | 2 +- classuvw_1_1FsPollHandle.html | 2 +- classuvw_1_1FsReq-members.html | 2 +- classuvw_1_1FsReq.html | 2 +- classuvw_1_1FsRequest-members.html | 2 +- classuvw_1_1FsRequest.html | 2 +- classuvw_1_1GetAddrInfoReq-members.html | 2 +- classuvw_1_1GetAddrInfoReq.html | 2 +- classuvw_1_1GetNameInfoReq-members.html | 2 +- classuvw_1_1GetNameInfoReq.html | 2 +- classuvw_1_1Handle-members.html | 2 +- classuvw_1_1Handle.html | 2 +- classuvw_1_1IdleHandle-members.html | 2 +- classuvw_1_1IdleHandle.html | 2 +- classuvw_1_1Loop-members.html | 2 +- classuvw_1_1Loop.html | 2 +- classuvw_1_1PipeHandle-members.html | 2 +- classuvw_1_1PipeHandle.html | 2 +- classuvw_1_1PollHandle-members.html | 2 +- classuvw_1_1PollHandle.html | 2 +- classuvw_1_1PrepareHandle-members.html | 2 +- classuvw_1_1PrepareHandle.html | 2 +- classuvw_1_1ProcessHandle-members.html | 2 +- classuvw_1_1ProcessHandle.html | 2 +- classuvw_1_1Resource-members.html | 2 +- classuvw_1_1Resource.html | 2 +- classuvw_1_1SharedLib-members.html | 2 +- classuvw_1_1SharedLib.html | 2 +- classuvw_1_1SignalHandle-members.html | 2 +- classuvw_1_1SignalHandle.html | 2 +- classuvw_1_1StreamHandle-members.html | 2 +- classuvw_1_1StreamHandle.html | 2 +- classuvw_1_1TTYHandle-members.html | 2 +- classuvw_1_1TTYHandle.html | 2 +- classuvw_1_1TcpHandle-members.html | 2 +- classuvw_1_1TcpHandle.html | 2 +- classuvw_1_1TimerHandle-members.html | 2 +- classuvw_1_1TimerHandle.html | 2 +- classuvw_1_1UDPHandle-members.html | 2 +- classuvw_1_1UDPHandle.html | 2 +- classuvw_1_1UnderlyingType-members.html | 2 +- classuvw_1_1UnderlyingType.html | 2 +- classuvw_1_1WorkReq-members.html | 2 +- classuvw_1_1WorkReq.html | 2 +- dir_68267d1309a1af8e8297ef4c3efbcdba.html | 2 +- dir_98934c98f70735fe3a272005a9eb8736.html | 2 +- dns_8hpp_source.html | 2 +- emitter_8hpp_source.html | 2 +- fs_8hpp_source.html | 2 +- fs__event_8hpp_source.html | 2 +- fs__poll_8hpp_source.html | 2 +- functions.html | 2 +- functions_b.html | 2 +- functions_c.html | 2 +- functions_d.html | 2 +- functions_e.html | 2 +- functions_f.html | 2 +- functions_func.html | 2 +- functions_func_b.html | 2 +- functions_func_c.html | 2 +- functions_func_d.html | 2 +- functions_func_e.html | 2 +- functions_func_f.html | 2 +- functions_func_g.html | 2 +- functions_func_h.html | 2 +- functions_func_i.html | 2 +- functions_func_k.html | 2 +- functions_func_l.html | 2 +- functions_func_m.html | 2 +- functions_func_n.html | 2 +- functions_func_o.html | 2 +- functions_func_p.html | 2 +- functions_func_q.html | 2 +- functions_func_r.html | 2 +- functions_func_s.html | 2 +- functions_func_t.html | 2 +- functions_func_u.html | 2 +- functions_func_w.html | 2 +- functions_g.html | 2 +- functions_h.html | 2 +- functions_i.html | 2 +- functions_k.html | 2 +- functions_l.html | 2 +- functions_m.html | 2 +- functions_n.html | 2 +- functions_o.html | 2 +- functions_p.html | 2 +- functions_q.html | 2 +- functions_r.html | 2 +- functions_s.html | 2 +- functions_t.html | 2 +- functions_u.html | 2 +- functions_vars.html | 2 +- functions_w.html | 2 +- graph_legend.html | 2 +- handle_8hpp_source.html | 2 +- hierarchy.html | 2 +- idle_8hpp_source.html | 2 +- index.html | 15 ++++++++------- inherits.html | 2 +- lib_8hpp_source.html | 2 +- loop_8hpp_source.html | 2 +- namespacemembers.html | 2 +- namespacemembers_type.html | 2 +- namespacemembers_vars.html | 2 +- namespaces.html | 2 +- namespaceuvw.html | 2 +- pipe_8hpp_source.html | 2 +- poll_8hpp_source.html | 2 +- prepare_8hpp_source.html | 2 +- process_8hpp_source.html | 2 +- request_8hpp_source.html | 2 +- resource_8hpp_source.html | 2 +- signal_8hpp_source.html | 2 +- stream_8hpp_source.html | 2 +- structuvw_1_1Addr-members.html | 2 +- structuvw_1_1Addr.html | 2 +- structuvw_1_1AddrInfoEvent-members.html | 2 +- structuvw_1_1AddrInfoEvent.html | 2 +- structuvw_1_1AsyncEvent.html | 2 +- structuvw_1_1BaseHandle-members.html | 2 +- structuvw_1_1BaseHandle.html | 2 +- structuvw_1_1CPUInfo-members.html | 2 +- structuvw_1_1CPUInfo.html | 2 +- structuvw_1_1CheckEvent.html | 2 +- structuvw_1_1CloseEvent.html | 2 +- structuvw_1_1ConnectEvent.html | 2 +- structuvw_1_1DataEvent-members.html | 2 +- structuvw_1_1DataEvent.html | 2 +- structuvw_1_1Emitter_1_1Connection-members.html | 2 +- structuvw_1_1Emitter_1_1Connection.html | 2 +- structuvw_1_1EndEvent.html | 2 +- structuvw_1_1ErrorEvent-members.html | 2 +- structuvw_1_1ErrorEvent.html | 2 +- structuvw_1_1ExitEvent-members.html | 2 +- structuvw_1_1ExitEvent.html | 2 +- structuvw_1_1FsEvent-members.html | 2 +- structuvw_1_1FsEvent.html | 2 +- structuvw_1_1FsEventEvent-members.html | 2 +- structuvw_1_1FsEventEvent.html | 2 +- ...details_1_1UVFsType_1_1FSTAT_01_4-members.html | 2 +- ...ent_3_01details_1_1UVFsType_1_1FSTAT_01_4.html | 2 +- ...details_1_1UVFsType_1_1LSTAT_01_4-members.html | 2 +- ...ent_3_01details_1_1UVFsType_1_1LSTAT_01_4.html | 2 +- ...ails_1_1UVFsType_1_1READLINK_01_4-members.html | 2 +- ..._3_01details_1_1UVFsType_1_1READLINK_01_4.html | 2 +- ...1details_1_1UVFsType_1_1READ_01_4-members.html | 2 +- ...vent_3_01details_1_1UVFsType_1_1READ_01_4.html | 2 +- ...tails_1_1UVFsType_1_1SCANDIR_01_4-members.html | 2 +- ...t_3_01details_1_1UVFsType_1_1SCANDIR_01_4.html | 2 +- ...ails_1_1UVFsType_1_1SENDFILE_01_4-members.html | 2 +- ..._3_01details_1_1UVFsType_1_1SENDFILE_01_4.html | 2 +- ...1details_1_1UVFsType_1_1STAT_01_4-members.html | 2 +- ...vent_3_01details_1_1UVFsType_1_1STAT_01_4.html | 2 +- ...details_1_1UVFsType_1_1WRITE_01_4-members.html | 2 +- ...ent_3_01details_1_1UVFsType_1_1WRITE_01_4.html | 2 +- structuvw_1_1FsHelper-members.html | 2 +- structuvw_1_1FsHelper.html | 2 +- structuvw_1_1FsPollEvent-members.html | 2 +- structuvw_1_1FsPollEvent.html | 2 +- structuvw_1_1IPv4.html | 2 +- structuvw_1_1IPv6.html | 2 +- structuvw_1_1IdleEvent.html | 2 +- structuvw_1_1InterfaceAddress-members.html | 2 +- structuvw_1_1InterfaceAddress.html | 2 +- structuvw_1_1ListenEvent.html | 2 +- structuvw_1_1NameInfoEvent-members.html | 2 +- structuvw_1_1NameInfoEvent.html | 2 +- structuvw_1_1Passwd-members.html | 2 +- structuvw_1_1Passwd.html | 2 +- structuvw_1_1PollEvent-members.html | 2 +- structuvw_1_1PollEvent.html | 2 +- structuvw_1_1PrepareEvent.html | 2 +- structuvw_1_1SendEvent.html | 2 +- structuvw_1_1ShutdownEvent.html | 2 +- structuvw_1_1SignalEvent-members.html | 2 +- structuvw_1_1SignalEvent.html | 2 +- structuvw_1_1TimerEvent.html | 2 +- structuvw_1_1UDPDataEvent-members.html | 2 +- structuvw_1_1UDPDataEvent.html | 2 +- structuvw_1_1Utilities-members.html | 2 +- structuvw_1_1Utilities.html | 2 +- structuvw_1_1Utilities_1_1OS-members.html | 2 +- structuvw_1_1Utilities_1_1OS.html | 2 +- structuvw_1_1WinSize-members.html | 2 +- structuvw_1_1WinSize.html | 2 +- structuvw_1_1WorkEvent.html | 2 +- structuvw_1_1WriteEvent.html | 2 +- tcp_8hpp_source.html | 2 +- thread_8hpp_source.html | 2 +- timer_8hpp_source.html | 2 +- tty_8hpp_source.html | 2 +- udp_8hpp_source.html | 2 +- underlying__type_8hpp_source.html | 2 +- util_8hpp_source.html | 2 +- uvw_8hpp_source.html | 2 +- work_8hpp_source.html | 2 +- 214 files changed, 222 insertions(+), 221 deletions(-) diff --git a/README_8md_source.html b/README_8md_source.html index 022ee982..e03c2a93 100644 --- a/README_8md_source.html +++ b/README_8md_source.html @@ -22,7 +22,7 @@
uvw -  1.11.0 +  1.11.1
@@ -63,7 +63,7 @@ $(function() {
README.md
-
1 **Sponsored and contributed by [Cynny SpA](https://www.cynny.com/).**
2 
3 # uvw - libuv wrapper in modern C++
4 
5 [![Build Status](https://travis-ci.org/skypjack/uvw.svg?branch=master)](https://travis-ci.org/skypjack/uvw)
6 [![Build status](https://ci.appveyor.com/api/projects/status/m5ndm8gnu8isg2to?svg=true)](https://ci.appveyor.com/project/skypjack/uvw)
7 [![Coverage Status](https://coveralls.io/repos/github/skypjack/uvw/badge.svg?branch=master)](https://coveralls.io/github/skypjack/uvw?branch=master)
8 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)
9 
10 # Introduction
11 
12 `uvw` is a header-only, event based, tiny and easy to use *libuv* wrapper in modern C++.<br/>
13 The basic idea is to hide completely the *C-ish* interface of *libuv* behind a graceful C++ API. Currently, no `uv_*_t` data structure is actually exposed by the library.<br/>
14 Note that `uvw` stays true to the API of *libuv* and it doesn't add anything to its interface. For the same reasons, users of the library must follow the same rules who are used to follow with *libuv*.<br/>
15 As an example, a *handle* should be initialized before any other operation and closed once it is no longer in use.
16 
17 ## Code Example
18 
19 ```cpp
20 #include <uvw.hpp>
21 #include <memory>
22 
23 void listen(uvw::Loop &loop) {
24  std::shared_ptr<uvw::TcpHandle> tcp = loop.resource<uvw::TcpHandle>();
25 
26  tcp->once<uvw::ListenEvent>([](const uvw::ListenEvent &, uvw::TcpHandle &srv) {
27  std::shared_ptr<uvw::TcpHandle> client = srv.loop().resource<uvw::TcpHandle>();
28 
29  client->on<uvw::CloseEvent>([ptr = srv.shared_from_this()](const uvw::CloseEvent &, uvw::TcpHandle &) { ptr->close(); });
30  client->on<uvw::EndEvent>([](const uvw::EndEvent &, uvw::TcpHandle &client) { client.close(); });
31 
32  srv.accept(*client);
33  client->read();
34  });
35 
36  tcp->bind("127.0.0.1", 4242);
37  tcp->listen();
38 }
39 
40 void conn(uvw::Loop &loop) {
41  auto tcp = loop.resource<uvw::TcpHandle>();
42 
43  tcp->on<uvw::ErrorEvent>([](const uvw::ErrorEvent &, uvw::TcpHandle &) { /* handle errors */ });
44 
45  tcp->once<uvw::ConnectEvent>([](const uvw::ConnectEvent &, uvw::TcpHandle &tcp) {
46  auto dataWrite = std::unique_ptr<char[]>(new char[2]{ 'b', 'c' });
47  tcp.write(std::move(dataWrite), 2);
48  tcp.close();
49  });
50 
51  tcp->connect(std::string{"127.0.0.1"}, 4242);
52 }
53 
54 int main() {
55  auto loop = uvw::Loop::getDefault();
56  listen(*loop);
57  conn(*loop);
58  loop->run();
59 }
60 ```
61 
62 ## Motivation
63 
64 The main reason for which `uvw` has been written is the fact that it does not exist a valid *libuv* wrapper in C++. That's all.
65 
66 # Build Instructions
67 
68 ## Requirements
69 
70 To be able to use `uvw`, users must provide the following system-wide tools:
71 
72 * A full-featured compiler that supports at least C++14.
73 * `libuv` (which version depends on the tag of `uvw` in use).
74 
75 The requirements below are mandatory to compile the tests and to extract the documentation:
76 
77 * CMake version 3.2 or later.
78 * Doxygen version 1.8 or later.
79 
80 Note that `libuv` is part of the dependencies of the project and it will be cloned by `cmake` (see below for further details).<br/>
81 Because of that, users have not to install it to compile and execute the tests.
82 
83 ## Library
84 
85 `uvw` is a header-only library.<br/>
86 This means that including the `uvw.hpp` header or one of the other `uvw/*.hpp` headers is enough to use it.<br/>
87 It's a matter of adding the following line at the top of a file:
88 
89 ```cpp
90 #include <uvw.hpp>
91 ```
92 
93 Then pass the proper `-I` argument to the compiler to add the `src` directory to the include paths.<br/>
94 Note that users are demanded to correctly setup include directories and libraries search paths for *libuv*.
95 
96 ## Versioning
97 
98 Starting with tag _v1.12.0_ of `libuv`, `uvw` follows the [semantic versioning](http://semver.org/) scheme.<br/>
99 The problem is that any version of `uvw` also requires to track explicitly the version of `libuv` to which it is bound.<br/>
100 Because of that, the latter wil be appended to the version of `uvw`. As an example:
101 
102  vU.V.W_libuv-vX.Y
103 
104 In particular, the following applies:
105 
106 * _U.V.W_ are major, minor and patch versions of `uvw`.
107 * _X.Y_ is the version of `libuv` to which to refer (where any patch version is valid).
108 
109 In other terms, tags will look like this from now on:
110 
111  v1.0.0_libuv-v1.12
112 
113 Branch `master` of `uvw` will be a work in progress branch that follows branch _v1.x_ of `libuv` (at least as long as it remains their _master_ branch).<br/>
114 
115 ## Documentation
116 
117 The documentation is based on [`doxygen`](http://www.stack.nl/~dimitri/doxygen/). To build it:
118 
119 * `$ cd build`
120 * `$ cmake ..`
121 * `$ make docs`
122 
123 The API reference will be created in HTML format within the directory `build/docs/html`.<br/>
124 To navigate it with your favorite browser:
125 
126 * `$ cd build`
127 * `$ your_favorite_browser docs/html/index.html`
128 
129 The API reference is also available [online](https://skypjack.github.io/uvw/) for the latest version.
130 
131 ### Note
132 
133 The documentation is mostly inspired by the official [libuv API documentation](http://docs.libuv.org/en/v1.x/) for obvious reasons.<br/>
134 If you are mainly interested in the way `uvw` imports `libuv` in a `cmake` based project, I suggest you to take a look at [this](https://github.com/skypjack/libuv_cmake) repository instead.
135 
136 ## Tests
137 
138 To compile and run the tests, `uvw` requires *libuv* and *googletest*.<br/>
139 `cmake` will download and compile both the libraries before to compile anything else.
140 
141 To build the tests:
142 
143 * `$ cd build`
144 * `$ cmake ..`
145 * `$ make`
146 * `$ make test`
147 
148 # Crash Course
149 
150 ## Vademecum
151 
152 There is only one rule when using `uvw`: always initialize the resources and terminate them.
153 
154 Resources belong mainly to two families: _handles_ and _requests_.<br/>
155 Handles represent long-lived objects capable of performing certain operations while active.<br/>
156 Requests represent (typically) short-lived operations performed either over a handle or standalone.
157 
158 The following sections will explain in short what it means to initialize and terminate these kinds of resources.<br/>
159 For more details, please refer to the [online documentation](https://skypjack.github.io/uvw/).
160 
161 ## Handles
162 
163 Initialization is usually performed under the hood and can be even passed over, as far as handles are created using the `Loop::resource` member function.<br/>
164 On the other side, handles keep themselves alive until one explicitly closes them. Because of that, memory usage will grow up if users simply forget about a handle.<br/>
165 Therefore the rule quickly becomes *always close your handles*. It's as simple as calling the `close` member function on them.
166 
167 ## Requests
168 
169 Usually initializing a request object is not required. Anyway, the recommended way to create a request is still through the `Loop::resource` member function.<br/>
170 Requests will keep themselves alive as long as they are bound to unfinished underlying activities. This means that users have not to discard explicitly a request.<br/>
171 Therefore the rule quickly becomes *feel free to make a request and forget about it*. It's as simple as calling a member function on them.
172 
173 ## The Loop and the Resource
174 
175 The first thing to do to use `uvw` is to create a loop. In case the default one is enough, it's easy as doing this:
176 
177 ```cpp
178 auto loop = uvw::Loop::getDefault();
179 ```
180 
181 Note that loop objects don't require to be closed explicitly, even if they offer the `close` member function in case an user wants to do that.<br/>
182 Loops can be started using the `run` member function. The two calls below are equivalent:
183 
184 ```cpp
185 loop->run();
186 loop->run<uvw::Loop::Mode::DEFAULT>();
187 ```
188 
189 Available modes are: `DEFAULT`, `ONCE`, `NOWAIT`. Please refer to the documentation of *libuv* for further details.
190 
191 In order to create a resource and to bind it to the given loop, just do the following:
192 
193 ```cpp
194 auto tcp = loop.resource<uvw::TcpHandle>();
195 ```
196 
197 The line above will create and initialize a tcp handle, then a shared pointer to that resource will be returned.<br/>
198 Users should check if pointers have been correctly initialized: in case of errors, they won't be.<br/>
199 Another way to create a resource is:
200 
201 ```cpp
202 auto tcp = TcpHandle::create(loop);
203 tcp->init();
204 ```
205 
206 Pretty annoying indeed. Using a loop is the recommended approach.
207 
208 The resources also accept arbitrary user-data that won't be touched in any case.<br/>
209 Users can set and get them through the `data` member function as it follows:
210 
211 ```cpp
212 resource->data(std::make_shared<int>(42));
213 std::shared_ptr<void> data = resource->data();
214 ```
215 
216 Resources expect a `std::shared_pointer<void>` and return it, therefore any kind of data is welcome.<br/>
217 Users can explicitly specify a type other than `void` when calling the `data` member function:
218 
219 ```cpp
220 std::shared_ptr<int> data = resource->data<int>();
221 ```
222 
223 Remember from the previous section that a handle will keep itself alive until one invokes the `close` member function on it.<br/>
224 To know what are the handles that are still alive and bound to a given loop, just do the following:
225 
226 ```cpp
227 loop.walk([](uvw::BaseHandle &){ /* application code here */ });
228 ```
229 
230 `BaseHandle` exposes a few methods and cannot be promoted to the original type of the handle (even though `type` and `category` member functions fill the gap somehow).<br/>
231 Anyway, it can be used to close the handle that originated from it. As an example, all the pending handles can be closed easily as it follows:
232 
233 ```cpp
234 loop.walk([](uvw::BaseHandle &h){ h.close(); });
235 ```
236 
237 No need to keep track of them.
238 
239 To know what are the available resources' types, please refer the API reference.
240 
241 ## The event-based approach
242 
243 For `uvw` offers an event-based approach, resources are small event emitters to which listeners can be attached.<br/>
244 Attaching a listener to a resource is the recommended way to be notified about changes.<br/>
245 Listeners must be callable objects of type `void(EventType &, ResourceType &)`, where:
246 
247 * `EventType` is the type of the event for which they have been designed.
248 * `ResourceType` is the type of the resource that has originated the event.
249 
250 It means that the following function types are all valid:
251 
252 * `void(EventType &, ResourceType &)`
253 * `void(const EventType &, ResourceType &)`
254 * `void(EventType &, const ResourceType &)`
255 * `void(const EventType &, const ResourceType &)`
256 
257 Once more, please note that there is no need to keep around references to the resources: they will pass themselves as an argument whenever an event is published.
258 
259 There exist two methods to attach an event to a resource:
260 
261 * `resource.once<EventType>(listener)`: the listener will be automatically removed after the first event of the given type.
262 * `resource.on<EventType>(listener)`: to be used for long-running listeners.
263 
264 Both of them return an object of type `ResourceType::Connection` (as an example, `TcpHandle::Connection`).<br/>
265 A connection object can be used later as an argument to the `erase` member function of the resource to remove the listener.<br/>
266 There exists also the `clear` member function to drop all the listeners at once.
267 
268 Almost all the resources use to emit `ErrorEvent` events in case of errors.<br/>
269 All the other events are specific for the given resource and documented in the API reference.
270 
271 The code below shows how to create a simple tcp server using `uvw`:
272 
273 ```cpp
274 auto loop = uvw::Loop::getDefault();
275 auto tcp = loop.resource<uvw::TcpHandle>();
276 
277 tcp->on<uvw::ErrorEvent>([](const uvw::ErrorEvent &, uvw::TcpHandle &) { /* something went wrong */ });
278 
279 tcp->on<uvw::ListenEvent>([](const uvw::ListenEvent &, uvw::TcpHandle &srv) {
280  std::shared_ptr<uvw::TcpHandle> client = srv.loop().resource<uvw::TcpHandle>();
281  client->once<uvw::EndEvent>([](const uvw::EndEvent &, uvw::TcpHandle &client) { client.close(); });
282  client->on<uvw::DataEvent>([](const uvw::DataEvent &, uvw::TcpHandle &) { /* data received */ });
283  srv.accept(*client);
284  client->read();
285 });
286 
287 tcp->bind("127.0.0.1", 4242);
288 tcp->listen();
289 ```
290 
291 Note also that `uvw::TcpHandle` already supports _IPv6_ out-of-the-box. The statement above is equivalent to `tcp->bind<uvw::IPv4>("127.0.0.1", 4242)`.<br/>
292 It's suffice to explicitly specify `uvw::IPv6` as the underlying protocol to use it.
293 
294 The API reference is the recommended documentation for further details about resources and their methods.
295 
296 ## Going raw
297 
298 In case users need to use functionalities not wrapped yet by `uvw` or if they
299 want to get the underlying data structures as defined by `libuv` for some other
300 reasons, almost all the classes in `uvw` give direct access to them.<br/>
301 Please, note that this functions should not be used directly unless users know
302 exactly what they are doing and what are the risks. Going raw is dangerous,
303 mainly because the lifetime management of a loop, a handle or a request is
304 completely in charge to the library and working around it could quickly break
305 things.
306 
307 That being said, _going raw_ is a matter of using the `raw` member functions:
308 
309 ```cpp
310 auto loop = uvw::Loop::getDefault();
311 auto tcp = loop.resource<uvw::TcpHandle>();
312 
313 uv_loop_t *raw = loop->raw();
314 uv_tcp_t *handle = tcp->raw();
315 ```
316 
317 Go the raw way at your own risk, but do not expect any support in case of bugs.
318 
319 # Contributors
320 
321 If you want to contribute, please send patches as pull requests against the branch master.<br/>
322 Check the [contributors list](https://github.com/skypjack/uvw/blob/master/AUTHORS) to see who has partecipated so far.
323 
324 # License
325 
326 Code and documentation Copyright (c) 2018 Michele Caini.<br/>
327 Code released under [the MIT license](https://github.com/skypjack/uvw/blob/master/LICENSE).<br/>
328 Docs released under [Creative Commons](https://github.com/skypjack/uvw/blob/master/docs/LICENSE).
329 
330 # Donation
331 
332 Developing and maintaining `uvw` takes some time and lots of coffee. It still lacks a proper test suite, documentation is partially incomplete and not all functionalities have been fully implemented yet.<br/>
333 If you want to support this project, you can offer me an espresso. I'm from Italy, we're used to turning the best coffee ever in code. If you find that it's not enough, feel free to support me the way you prefer.<br/>
334 Take a look at the donation button at the top of the page for more details or just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).
+
1 ![uvw - libuv wrapper in modern C++](https://user-images.githubusercontent.com/1812216/46069406-c977a600-c17b-11e8-9a47-9bba6f412c57.png)
2 
3 <!--
4 @cond TURN_OFF_DOXYGEN
5 -->
6 [![Build Status](https://travis-ci.org/skypjack/uvw.svg?branch=master)](https://travis-ci.org/skypjack/uvw)
7 [![Build status](https://ci.appveyor.com/api/projects/status/m5ndm8gnu8isg2to?svg=true)](https://ci.appveyor.com/project/skypjack/uvw)
8 [![Coverage Status](https://coveralls.io/repos/github/skypjack/uvw/badge.svg?branch=master)](https://coveralls.io/github/skypjack/uvw?branch=master)
9 [![Gitter chat](https://badges.gitter.im/skypjack/uvw.png)](https://gitter.im/skypjack/uvw)
10 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)
11 <!--
12 @endcond TURN_OFF_DOXYGEN
13 -->
14 
15 # Introduction
16 
17 `uvw` is a header-only, event based, tiny and easy to use *libuv* wrapper in modern C++.<br/>
18 The basic idea is to hide completely the *C-ish* interface of *libuv* behind a graceful C++ API. Currently, no `uv_*_t` data structure is actually exposed by the library.<br/>
19 Note that `uvw` stays true to the API of *libuv* and it doesn't add anything to its interface. For the same reasons, users of the library must follow the same rules who are used to follow with *libuv*.<br/>
20 As an example, a *handle* should be initialized before any other operation and closed once it is no longer in use.
21 
22 ## Code Example
23 
24 ```cpp
25 #include <uvw.hpp>
26 #include <memory>
27 
28 void listen(uvw::Loop &loop) {
29  std::shared_ptr<uvw::TcpHandle> tcp = loop.resource<uvw::TcpHandle>();
30 
31  tcp->once<uvw::ListenEvent>([](const uvw::ListenEvent &, uvw::TcpHandle &srv) {
32  std::shared_ptr<uvw::TcpHandle> client = srv.loop().resource<uvw::TcpHandle>();
33 
34  client->on<uvw::CloseEvent>([ptr = srv.shared_from_this()](const uvw::CloseEvent &, uvw::TcpHandle &) { ptr->close(); });
35  client->on<uvw::EndEvent>([](const uvw::EndEvent &, uvw::TcpHandle &client) { client.close(); });
36 
37  srv.accept(*client);
38  client->read();
39  });
40 
41  tcp->bind("127.0.0.1", 4242);
42  tcp->listen();
43 }
44 
45 void conn(uvw::Loop &loop) {
46  auto tcp = loop.resource<uvw::TcpHandle>();
47 
48  tcp->on<uvw::ErrorEvent>([](const uvw::ErrorEvent &, uvw::TcpHandle &) { /* handle errors */ });
49 
50  tcp->once<uvw::ConnectEvent>([](const uvw::ConnectEvent &, uvw::TcpHandle &tcp) {
51  auto dataWrite = std::unique_ptr<char[]>(new char[2]{ 'b', 'c' });
52  tcp.write(std::move(dataWrite), 2);
53  tcp.close();
54  });
55 
56  tcp->connect(std::string{"127.0.0.1"}, 4242);
57 }
58 
59 int main() {
60  auto loop = uvw::Loop::getDefault();
61  listen(*loop);
62  conn(*loop);
63  loop->run();
64 }
65 ```
66 
67 ## Motivation
68 
69 The main reason for which `uvw` has been written is the fact that it does not exist a valid *libuv* wrapper in C++. That's all.
70 
71 # Build Instructions
72 
73 ## Requirements
74 
75 To be able to use `uvw`, users must provide the following system-wide tools:
76 
77 * A full-featured compiler that supports at least C++14.
78 * `libuv` (which version depends on the tag of `uvw` in use).
79 
80 The requirements below are mandatory to compile the tests and to extract the documentation:
81 
82 * CMake version 3.2 or later.
83 * Doxygen version 1.8 or later.
84 
85 Note that `libuv` is part of the dependencies of the project and it will be cloned by `cmake` (see below for further details).<br/>
86 Because of that, users have not to install it to compile and execute the tests.
87 
88 ## Library
89 
90 `uvw` is a header-only library.<br/>
91 This means that including the `uvw.hpp` header or one of the other `uvw/*.hpp` headers is enough to use it.<br/>
92 It's a matter of adding the following line at the top of a file:
93 
94 ```cpp
95 #include <uvw.hpp>
96 ```
97 
98 Then pass the proper `-I` argument to the compiler to add the `src` directory to the include paths.<br/>
99 Note that users are demanded to correctly setup include directories and libraries search paths for *libuv*.
100 
101 ## Versioning
102 
103 Starting with tag _v1.12.0_ of `libuv`, `uvw` follows the [semantic versioning](http://semver.org/) scheme.<br/>
104 The problem is that any version of `uvw` also requires to track explicitly the version of `libuv` to which it is bound.<br/>
105 Because of that, the latter wil be appended to the version of `uvw`. As an example:
106 
107  vU.V.W_libuv-vX.Y
108 
109 In particular, the following applies:
110 
111 * _U.V.W_ are major, minor and patch versions of `uvw`.
112 * _X.Y_ is the version of `libuv` to which to refer (where any patch version is valid).
113 
114 In other terms, tags will look like this from now on:
115 
116  v1.0.0_libuv-v1.12
117 
118 Branch `master` of `uvw` will be a work in progress branch that follows branch _v1.x_ of `libuv` (at least as long as it remains their _master_ branch).<br/>
119 
120 ## Documentation
121 
122 The documentation is based on [`doxygen`](http://www.stack.nl/~dimitri/doxygen/). To build it:
123 
124 * `$ cd build`
125 * `$ cmake ..`
126 * `$ make docs`
127 
128 The API reference will be created in HTML format within the directory `build/docs/html`.<br/>
129 To navigate it with your favorite browser:
130 
131 * `$ cd build`
132 * `$ your_favorite_browser docs/html/index.html`
133 
134 The API reference is also available [online](https://skypjack.github.io/uvw/) for the latest version.
135 
136 ### Note
137 
138 The documentation is mostly inspired by the official [libuv API documentation](http://docs.libuv.org/en/v1.x/) for obvious reasons.<br/>
139 If you are mainly interested in the way `uvw` imports `libuv` in a `cmake` based project, I suggest you to take a look at [this](https://github.com/skypjack/libuv_cmake) repository instead.
140 
141 ## Tests
142 
143 To compile and run the tests, `uvw` requires *libuv* and *googletest*.<br/>
144 `cmake` will download and compile both the libraries before to compile anything else.
145 
146 To build the tests:
147 
148 * `$ cd build`
149 * `$ cmake ..`
150 * `$ make`
151 * `$ make test`
152 
153 # Crash Course
154 
155 ## Vademecum
156 
157 There is only one rule when using `uvw`: always initialize the resources and terminate them.
158 
159 Resources belong mainly to two families: _handles_ and _requests_.<br/>
160 Handles represent long-lived objects capable of performing certain operations while active.<br/>
161 Requests represent (typically) short-lived operations performed either over a handle or standalone.
162 
163 The following sections will explain in short what it means to initialize and terminate these kinds of resources.<br/>
164 For more details, please refer to the [online documentation](https://skypjack.github.io/uvw/).
165 
166 ## Handles
167 
168 Initialization is usually performed under the hood and can be even passed over, as far as handles are created using the `Loop::resource` member function.<br/>
169 On the other side, handles keep themselves alive until one explicitly closes them. Because of that, memory usage will grow up if users simply forget about a handle.<br/>
170 Therefore the rule quickly becomes *always close your handles*. It's as simple as calling the `close` member function on them.
171 
172 ## Requests
173 
174 Usually initializing a request object is not required. Anyway, the recommended way to create a request is still through the `Loop::resource` member function.<br/>
175 Requests will keep themselves alive as long as they are bound to unfinished underlying activities. This means that users have not to discard explicitly a request.<br/>
176 Therefore the rule quickly becomes *feel free to make a request and forget about it*. It's as simple as calling a member function on them.
177 
178 ## The Loop and the Resource
179 
180 The first thing to do to use `uvw` is to create a loop. In case the default one is enough, it's easy as doing this:
181 
182 ```cpp
183 auto loop = uvw::Loop::getDefault();
184 ```
185 
186 Note that loop objects don't require to be closed explicitly, even if they offer the `close` member function in case an user wants to do that.<br/>
187 Loops can be started using the `run` member function. The two calls below are equivalent:
188 
189 ```cpp
190 loop->run();
191 loop->run<uvw::Loop::Mode::DEFAULT>();
192 ```
193 
194 Available modes are: `DEFAULT`, `ONCE`, `NOWAIT`. Please refer to the documentation of *libuv* for further details.
195 
196 In order to create a resource and to bind it to the given loop, just do the following:
197 
198 ```cpp
199 auto tcp = loop.resource<uvw::TcpHandle>();
200 ```
201 
202 The line above will create and initialize a tcp handle, then a shared pointer to that resource will be returned.<br/>
203 Users should check if pointers have been correctly initialized: in case of errors, they won't be.<br/>
204 Another way to create a resource is:
205 
206 ```cpp
207 auto tcp = TcpHandle::create(loop);
208 tcp->init();
209 ```
210 
211 Pretty annoying indeed. Using a loop is the recommended approach.
212 
213 The resources also accept arbitrary user-data that won't be touched in any case.<br/>
214 Users can set and get them through the `data` member function as it follows:
215 
216 ```cpp
217 resource->data(std::make_shared<int>(42));
218 std::shared_ptr<void> data = resource->data();
219 ```
220 
221 Resources expect a `std::shared_pointer<void>` and return it, therefore any kind of data is welcome.<br/>
222 Users can explicitly specify a type other than `void` when calling the `data` member function:
223 
224 ```cpp
225 std::shared_ptr<int> data = resource->data<int>();
226 ```
227 
228 Remember from the previous section that a handle will keep itself alive until one invokes the `close` member function on it.<br/>
229 To know what are the handles that are still alive and bound to a given loop, just do the following:
230 
231 ```cpp
232 loop.walk([](uvw::BaseHandle &){ /* application code here */ });
233 ```
234 
235 `BaseHandle` exposes a few methods and cannot be promoted to the original type of the handle (even though `type` and `category` member functions fill the gap somehow).<br/>
236 Anyway, it can be used to close the handle that originated from it. As an example, all the pending handles can be closed easily as it follows:
237 
238 ```cpp
239 loop.walk([](uvw::BaseHandle &h){ h.close(); });
240 ```
241 
242 No need to keep track of them.
243 
244 To know what are the available resources' types, please refer the API reference.
245 
246 ## The event-based approach
247 
248 For `uvw` offers an event-based approach, resources are small event emitters to which listeners can be attached.<br/>
249 Attaching a listener to a resource is the recommended way to be notified about changes.<br/>
250 Listeners must be callable objects of type `void(EventType &, ResourceType &)`, where:
251 
252 * `EventType` is the type of the event for which they have been designed.
253 * `ResourceType` is the type of the resource that has originated the event.
254 
255 It means that the following function types are all valid:
256 
257 * `void(EventType &, ResourceType &)`
258 * `void(const EventType &, ResourceType &)`
259 * `void(EventType &, const ResourceType &)`
260 * `void(const EventType &, const ResourceType &)`
261 
262 Once more, please note that there is no need to keep around references to the resources: they will pass themselves as an argument whenever an event is published.
263 
264 There exist two methods to attach an event to a resource:
265 
266 * `resource.once<EventType>(listener)`: the listener will be automatically removed after the first event of the given type.
267 * `resource.on<EventType>(listener)`: to be used for long-running listeners.
268 
269 Both of them return an object of type `ResourceType::Connection` (as an example, `TcpHandle::Connection`).<br/>
270 A connection object can be used later as an argument to the `erase` member function of the resource to remove the listener.<br/>
271 There exists also the `clear` member function to drop all the listeners at once.
272 
273 Almost all the resources use to emit `ErrorEvent` events in case of errors.<br/>
274 All the other events are specific for the given resource and documented in the API reference.
275 
276 The code below shows how to create a simple tcp server using `uvw`:
277 
278 ```cpp
279 auto loop = uvw::Loop::getDefault();
280 auto tcp = loop.resource<uvw::TcpHandle>();
281 
282 tcp->on<uvw::ErrorEvent>([](const uvw::ErrorEvent &, uvw::TcpHandle &) { /* something went wrong */ });
283 
284 tcp->on<uvw::ListenEvent>([](const uvw::ListenEvent &, uvw::TcpHandle &srv) {
285  std::shared_ptr<uvw::TcpHandle> client = srv.loop().resource<uvw::TcpHandle>();
286  client->once<uvw::EndEvent>([](const uvw::EndEvent &, uvw::TcpHandle &client) { client.close(); });
287  client->on<uvw::DataEvent>([](const uvw::DataEvent &, uvw::TcpHandle &) { /* data received */ });
288  srv.accept(*client);
289  client->read();
290 });
291 
292 tcp->bind("127.0.0.1", 4242);
293 tcp->listen();
294 ```
295 
296 Note also that `uvw::TcpHandle` already supports _IPv6_ out-of-the-box. The statement above is equivalent to `tcp->bind<uvw::IPv4>("127.0.0.1", 4242)`.<br/>
297 It's suffice to explicitly specify `uvw::IPv6` as the underlying protocol to use it.
298 
299 The API reference is the recommended documentation for further details about resources and their methods.
300 
301 ## Going raw
302 
303 In case users need to use functionalities not wrapped yet by `uvw` or if they
304 want to get the underlying data structures as defined by `libuv` for some other
305 reasons, almost all the classes in `uvw` give direct access to them.<br/>
306 Please, note that this functions should not be used directly unless users know
307 exactly what they are doing and what are the risks. Going raw is dangerous,
308 mainly because the lifetime management of a loop, a handle or a request is
309 completely in charge to the library and working around it could quickly break
310 things.
311 
312 That being said, _going raw_ is a matter of using the `raw` member functions:
313 
314 ```cpp
315 auto loop = uvw::Loop::getDefault();
316 auto tcp = loop.resource<uvw::TcpHandle>();
317 
318 uv_loop_t *raw = loop->raw();
319 uv_tcp_t *handle = tcp->raw();
320 ```
321 
322 Go the raw way at your own risk, but do not expect any support in case of bugs.
323 
324 # Contributors
325 
326 If you want to contribute, please send patches as pull requests against the branch master.<br/>
327 Check the [contributors list](https://github.com/skypjack/uvw/blob/master/AUTHORS) to see who has partecipated so far.
328 
329 # License
330 
331 Code and documentation Copyright (c) 2017-2018 Michele Caini.<br/>
332 Logo Copyright (c) 2018 Richard Caseres.
333 
334 Code released under
335 [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).
336 Documentation released under
337 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).<br/>
338 Logo released under
339 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
340 
341 # Donation
342 
343 Developing and maintaining `uvw` takes some time and lots of coffee. It still lacks a proper test suite, documentation is partially incomplete and not all functionalities have been fully implemented yet.<br/>
344 If you want to support this project, you can offer me an espresso. I'm from Italy, we're used to turning the best coffee ever in code. If you find that it's not enough, feel free to support me the way you prefer.<br/>
345 Take a look at the donation button at the top of the page for more details or just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).