fixed #114

CMakeLists.txt

@@ -16,7 +16,7 @@ endif()
 # Project configuration
 #
 
-project(uvw VERSION 1.8.0)
+project(uvw VERSION 1.8.1)
 
 if(NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Debug)

README.md

@@ -293,24 +293,34 @@ It's suffice to explicitly specify `uvw::IPv6` as the underlying protocol to use
 
 The API reference is the recommended documentation for further details about resources and their methods.
 
+## Going raw
+
+In case users need to use functionalities not wrapped yet by `uvw` or if they
+want to get the underlying data structures as defined by `libuv` for some other
+reasons, almost all the classes in `uvw` give direct access to them.<br/>
+Please, note that this functions should not be used directly unless users know
+exactly what they are doing and what are the risks. Going raw is dangerous,
+mainly because the lifetime management of a loop, a handle or a request is
+completely in charge to the library and working around it could quickly break
+things.
+
+That being said, _going raw_ is a matter of using the `raw` member functions:
+
+```cpp
+auto loop = uvw::Loop::getDefault();
+auto tcp = loop.resource<uvw::TcpHandle>();
+
+uv_loop_t *raw = loop->raw();
+uv_tcp_t *handle = tcp->raw();
+```
+
+Go the raw way at your own risk, but do not expect any support in case of bugs.
+
 # Contributors
 
 If you want to contribute, please send patches as pull requests against the branch master.<br/>
 Check the [contributors list](https://github.com/skypjack/uvw/blob/master/AUTHORS) to see who has partecipated so far.
 
-# Projects that use `uvw`
-
-Below an incomplete list of projects that use `uvw`:
-
-* Internal tools (not publicly available) at **[Cynny SpA](https://www.morphcast.com/)** and **[Cynny Space](http://www.cynnyspace.com/)**.
-* **[Calaos.fr](https://www.calaos.fr/en/)** (Open source home automation) on [GitHub](https://github.com/calaos).
-* **[Iroha](http://iroha.tech/en/) - A simple, decentralized ledger** on [Github](https://github.com/hyperledger/iroha).
-* **Iroha blockchain core** on [Github](https://github.com/finshield/iroha-core).
-* **Ecwid Console Downloader** on [GitHub](https://github.com/dvetutnev/Ecwid-Console-downloader).
-* **Simple network ping pong for lazy students** on [GitHub](https://github.com/dvetutnev/ping_pong).
-
-If you know of other projects that use `libuv` through `uvw`, feel free to open a PR and I'll be glad to add them to the list.
-
 # License
 
 Code and documentation Copyright (c) 2018 Michele Caini.<br/>

src/uvw/loop.hpp

@@ -449,6 +449,44 @@ public:
         userData = std::move(uData);
     }
 
+    /**
+     * @brief Gets the underlying raw data structure.
+     *
+     * This function should not be used, unless you know exactly what you are
+     * doing and what are the risks.<br/>
+     * Going raw is dangerous, mainly because the lifetime management of a loop,
+     * a handle or a request is in charge to the library itself and users should
+     * not work around it.
+     *
+     * @warning
+     * Use this function at your own risk, but do not expect any support in case
+     * of bugs.
+     *
+     * @return The underlying raw data structure.
+     */
+    const uv_loop_t * raw() const noexcept {
+        return loop.get();
+    }
+
+    /**
+     * @brief Gets the underlying raw data structure.
+     *
+     * This function should not be used, unless you know exactly what you are
+     * doing and what are the risks.<br/>
+     * Going raw is dangerous, mainly because the lifetime management of a loop,
+     * a handle or a request is in charge to the library itself and users should
+     * not work around it.
+     *
+     * @warning
+     * Use this function at your own risk, but do not expect any support in case
+     * of bugs.
+     *
+     * @return The underlying raw data structure.
+     */
+    uv_loop_t * raw() noexcept {
+        return const_cast<uv_loop_t *>(const_cast<const Loop *>(this)->raw());
+    }
+
 private:
     std::unique_ptr<uv_loop_t, Deleter> loop;
     std::shared_ptr<void> userData{nullptr};

src/uvw/underlying_type.hpp

@@ -84,6 +84,44 @@ public:
      */
     Loop & loop() const noexcept { return *pLoop; }
 
+    /**
+     * @brief Gets the underlying raw data structure.
+     *
+     * This function should not be used, unless you know exactly what you are
+     * doing and what are the risks.<br/>
+     * Going raw is dangerous, mainly because the lifetime management of a loop,
+     * a handle or a request is in charge to the library itself and users should
+     * not work around it.
+     *
+     * @warning
+     * Use this function at your own risk, but do not expect any support in case
+     * of bugs.
+     *
+     * @return The underlying raw data structure.
+     */
+    const U * raw() const noexcept {
+        return &resource;
+    }
+
+    /**
+     * @brief Gets the underlying raw data structure.
+     *
+     * This function should not be used, unless you know exactly what you are
+     * doing and what are the risks.<br/>
+     * Going raw is dangerous, mainly because the lifetime management of a loop,
+     * a handle or a request is in charge to the library itself and users should
+     * not work around it.
+     *
+     * @warning
+     * Use this function at your own risk, but do not expect any support in case
+     * of bugs.
+     *
+     * @return The underlying raw data structure.
+     */
+    U * raw() noexcept {
+        return const_cast<U *>(const_cast<const UnderlyingType *>(this)->raw());
+    }
+
 private:
     std::shared_ptr<Loop> pLoop;
     U resource;

test/uvw/loop.cpp

@@ -81,3 +81,13 @@ TEST(Loop, Configure) {
     ASSERT_NO_THROW(loop->configure(uvw::Loop::Configure::BLOCK_SIGNAL, 9));
     ASSERT_NO_THROW(loop->run());
 }
+
+TEST(Loop, Raw) {
+    auto loop = uvw::Loop::getDefault();
+    const auto &cloop = uvw::Loop::getDefault();
+
+    auto *raw = loop->raw();
+    auto *craw = cloop->raw();
+
+    ASSERT_EQ(raw, craw);
+}

test/uvw/underlying_type.cpp

@@ -9,3 +9,14 @@ TEST(UnderlyingType, Functionalities) {
     ASSERT_TRUE(handle);
     ASSERT_EQ(&handle->loop(), loop.get());
 }
+
+TEST(UnderlyingType, Raw) {
+    auto loop = uvw::Loop::getDefault();
+    auto handle = uvw::AsyncHandle::create(loop);
+    const auto &chandle = handle;
+
+    auto *raw = handle->raw();
+    auto *craw = chandle->raw();
+
+    ASSERT_EQ(raw, craw);
+}