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 @@
1 
6 [](https://travis-ci.org/skypjack/uvw)
7 [](https://ci.appveyor.com/project/skypjack/uvw)
8 [](https://coveralls.io/github/skypjack/uvw?branch=master)
9 [](https://gitter.im/skypjack/uvw)
10 [](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)
12 @endcond TURN_OFF_DOXYGEN
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.
28 void listen(uvw::Loop &loop) {
29 std::shared_ptr<uvw::TcpHandle> tcp = loop.resource<uvw::TcpHandle>();
31 tcp->once<uvw::ListenEvent>([](const uvw::ListenEvent &, uvw::TcpHandle &srv) {
32 std::shared_ptr<uvw::TcpHandle> client = srv.loop().resource<uvw::TcpHandle>();
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(); });
41 tcp->bind("127.0.0.1", 4242);
45 void conn(uvw::Loop &loop) {
46 auto tcp = loop.resource<uvw::TcpHandle>();
48 tcp->on<uvw::ErrorEvent>([](const uvw::ErrorEvent &, uvw::TcpHandle &) { /* handle errors */ });
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);
56 tcp->connect(std::string{"127.0.0.1"}, 4242);
60 auto loop = uvw::Loop::getDefault();
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.
75 To be able to use `uvw`, users must provide the following system-wide tools:
77 * A full-featured compiler that supports at least C++14.
78 * `libuv` (which version depends on the tag of `uvw` in use).
80 The requirements below are mandatory to compile the tests and to extract the documentation:
82 * CMake version 3.2 or later.
83 * Doxygen version 1.8 or later.
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.
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:
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*.
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:
109 In particular, the following applies:
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).
114 In other terms, tags will look like this from now on:
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/>
122 The documentation is based on [`doxygen`](http://www.stack.nl/~dimitri/doxygen/). To build it:
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:
132 * `$ your_favorite_browser docs/html/index.html`
134 The API reference is also available [online](https://skypjack.github.io/uvw/) for the latest version.
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.
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.
157 There is only one rule when using `uvw`: always initialize the resources and terminate them.
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.
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/).
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.
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.
178 ## The Loop and the Resource
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:
183 auto loop = uvw::Loop::getDefault();
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:
191 loop->run<uvw::Loop::Mode::DEFAULT>();
194 Available modes are: `DEFAULT`, `ONCE`, `NOWAIT`. Please refer to the documentation of *libuv* for further details.
196 In order to create a resource and to bind it to the given loop, just do the following:
199 auto tcp = loop.resource<uvw::TcpHandle>();
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:
207 auto tcp = TcpHandle::create(loop);
211 Pretty annoying indeed. Using a loop is the recommended approach.
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:
217 resource->data(std::make_shared<int>(42));
218 std::shared_ptr<void> data = resource->data();
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:
225 std::shared_ptr<int> data = resource->data<int>();
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:
232 loop.walk([](uvw::BaseHandle &){ /* application code here */ });
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:
239 loop.walk([](uvw::BaseHandle &h){ h.close(); });
242 No need to keep track of them.
244 To know what are the available resources' types, please refer the API reference.
246 ## The event-based approach
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:
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.
255 It means that the following function types are all valid:
257 * `void(EventType &, ResourceType &)`
258 * `void(const EventType &, ResourceType &)`
259 * `void(EventType &, const ResourceType &)`
260 * `void(const EventType &, const ResourceType &)`
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.
264 There exist two methods to attach an event to a resource:
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.
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.
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.
276 The code below shows how to create a simple tcp server using `uvw`:
279 auto loop = uvw::Loop::getDefault();
280 auto tcp = loop.resource<uvw::TcpHandle>();
282 tcp->on<uvw::ErrorEvent>([](const uvw::ErrorEvent &, uvw::TcpHandle &) { /* something went wrong */ });
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 */ });
292 tcp->bind("127.0.0.1", 4242);
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.
299 The API reference is the recommended documentation for further details about resources and their methods.
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
312 That being said, _going raw_ is a matter of using the `raw` member functions:
315 auto loop = uvw::Loop::getDefault();
316 auto tcp = loop.resource<uvw::TcpHandle>();
318 uv_loop_t *raw = loop->raw();
319 uv_tcp_t *handle = tcp->raw();
322 Go the raw way at your own risk, but do not expect any support in case of bugs.
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.
331 Code and documentation Copyright (c) 2017-2018 Michele Caini.<br/>
332 Logo Copyright (c) 2018 Richard Caseres.
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/>
339 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
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¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).