diff --git a/src/uvw/async.hpp b/src/uvw/async.hpp index 2ea5a7ef..db7c2ffc 100644 --- a/src/uvw/async.hpp +++ b/src/uvw/async.hpp @@ -13,7 +13,7 @@ namespace uvw { /** - * @brief Trigger event. + * @brief AsyncEvent event. * * It will be emitted by the AsyncHandle according with its functionalities. */ diff --git a/src/uvw/check.hpp b/src/uvw/check.hpp index 33b65646..2c9d084a 100644 --- a/src/uvw/check.hpp +++ b/src/uvw/check.hpp @@ -13,7 +13,7 @@ namespace uvw { /** - * @brief Trigger event. + * @brief CheckEvent event. * * It will be emitted by the CheckHandle according with its functionalities. */ diff --git a/src/uvw/handle.hpp b/src/uvw/handle.hpp index 48e4d3de..4755d941 100644 --- a/src/uvw/handle.hpp +++ b/src/uvw/handle.hpp @@ -11,9 +11,19 @@ namespace uvw { +/** + * @brief CloseEvent event. + * + * It will be emitted by the handles according with their functionalities. + */ struct CloseEvent: Event { }; +/** + * @brief Handle base class. + * + * Base type for all `uvw` handle types. + */ template class Handle: public BaseHandle, public Resource { @@ -71,52 +81,168 @@ protected: } public: + /** + * @brief Checks if the handle is active. + * + * What _active_ means depends on the type of handle: + * + * * An AsyncHandle handle is always active and cannot be deactivated, + * except by closing it with uv_close(). + * * A PipeHandle, TcpHandle, UDPHandle, etc. handle - basically any handle + * that deals with I/O - is active when it is doing something that involves + * I/O, like reading, writing, connecting, accepting new connections, etc. + * * A CheckHandle, IdleHandle, TimerHandle, etc. handle is active when it + * has been started with a call to `start()`. + * + * Rule of thumb: if a handle of type `FooHandle` has a `start()` member + * method, then it’s active from the moment that method is called. Likewise, + * `stop()` deactivates the handle again. + * + * @return True if the handle is active, false otherwise. + */ bool active() const noexcept override { return !(uv_is_active(this->template get()) == 0); } + /** + * @brief Checks if a handle is closing or closed. + * + * This function should only be used between the initialization of the + * handle and the arrival of the close callback. + * + * @return True if the handle is closing or closed, false otherwise. + */ bool closing() const noexcept override { return !(uv_is_closing(this->template get()) == 0); } + /** + * @brief Request handle to be closed. + * + * This **must** be called on each handle before memory is released.
+ * In-progress requests are cancelled and this can result in an ErrorEvent + * emitted. + */ void close() noexcept override { if(!closing()) { uv_close(this->template get(), &Handle::closeCallback); } } + /** + * @brief Reference the given handle. + * + * References are idempotent, that is, if a handle is already referenced + * calling this function again will have no effect. + */ void reference() noexcept override { uv_ref(this->template get()); } + /** + * @brief Unreference the given handle. + * + * References are idempotent, that is, if a handle is not referenced calling + * this function again will have no effect. + */ void unreference() noexcept override { uv_unref(this->template get()); } + /** + * @brief Checks if the given handle referenced. + * @return True if the handle referenced, false otherwise. + */ bool referenced() const noexcept override { return !(uv_has_ref(this->template get()) == 0); } + /** + * @brief Returns the size of the underlying handle type. + * @return The size of the underlying handle type. + */ std::size_t size() const noexcept { return uv_handle_size(this->template get()->type); } + /** + * @brief Gets the size of the send buffer used for the socket. + * + * Gets the size of the send buffer that the operating system uses for the + * socket.
+ * This function works for TcpHandle, PipeHandle and UDPHandle handles on + * Unix and for TcpHandle and UDPHandle handles on Windows.
+ * Note that Linux will return double the size of the original set value. + * + * @return The size of the send buffer used for the socket. + */ int sendBufferSize() const { return setBufferSize(&uv_send_buffer_size); } + /** + * @brief Sets the size of the send buffer used for the socket. + * + * Sets the size of the send buffer that the operating system uses for the + * socket.
+ * This function works for TcpHandle, PipeHandle and UDPHandle handles on + * Unix and for TcpHandle and UDPHandle handles on Windows.
+ * Note that Linux will set double the size. + */ void sendBufferSize(int value) { getBufferSize(&uv_send_buffer_size, value); } + /** + * @brief Gets the size of the receive buffer used for the socket. + * + * Gets the size of the receive buffer that the operating system uses for + * the socket.
+ * This function works for TcpHandle, PipeHandle and UDPHandle handles on + * Unix and for TcpHandle and UDPHandle handles on Windows.
+ * Note that Linux will return double the size of the original set value. + * + * @return The size of the receive buffer used for the socket. + */ int recvBufferSize() const { return setBufferSize(&uv_recv_buffer_size); } + /** + * @brief Sets the size of the receive buffer used for the socket. + * + * Sets the size of the receive buffer that the operating system uses for + * the socket.
+ * This function works for TcpHandle, PipeHandle and UDPHandle handles on + * Unix and for TcpHandle and UDPHandle handles on Windows.
+ * Note that Linux will set double the size. + */ void recvBufferSize(int value) { getBufferSize(&uv_recv_buffer_size, value); } + /** + * @brief Gets the platform dependent file descriptor equivalent. + * + * Supported handles: + * + * * TcpHandle + * * PipeHandle + * * TTYHandle + * * UDPHandle + * * PollHandle + * + * It will emit an ErrorEvent event if invoked on any other handle.
+ * If a handle doesn’t have an attached file descriptor yet or the handle + * itself has been closed, an ErrorEvent event will be emitted. + * + * See the official + * [documentation](http://docs.libuv.org/en/v1.x/handle.html#c.uv_fileno) + * for further details. + * + * @return The file descriptor attached to the hande or a negative value in + * case of errors. + */ OSFileDescriptor fileno() const { uv_os_fd_t fd; invoke(&uv_fileno, this->template get(), &fd); diff --git a/src/uvw/idle.hpp b/src/uvw/idle.hpp index 346653bb..5df93e7b 100644 --- a/src/uvw/idle.hpp +++ b/src/uvw/idle.hpp @@ -13,7 +13,7 @@ namespace uvw { /** - * @brief Trigger event. + * @brief IdleEvent event. * * It will be emitted by the IdleHandle according with its functionalities. */ diff --git a/src/uvw/loop.hpp b/src/uvw/loop.hpp index baac9211..208173b1 100644 --- a/src/uvw/loop.hpp +++ b/src/uvw/loop.hpp @@ -43,14 +43,23 @@ enum class UVRunMode: std::underlying_type_t { class BaseHandle { public: /** - * @brief Checks if a handle is active. + * @brief Checks if the handle is active. * - * What _active_ means depends on the type of handle.
- * See the official - * [documentation](http://docs.libuv.org/en/v1.x/handle.html#c.uv_is_active) - * for further details. + * What _active_ means depends on the type of handle: * - * @return Non-zero if the handle is active, zero if it’s inactive. + * * An AsyncHandle handle is always active and cannot be deactivated, + * except by closing it with uv_close(). + * * A PipeHandle, TcpHandle, UDPHandle, etc. handle - basically any handle + * that deals with I/O - is active when it is doing something that involves + * I/O, like reading, writing, connecting, accepting new connections, etc. + * * A CheckHandle, IdleHandle, TimerHandle, etc. handle is active when it + * has been started with a call to `start()`. + * + * Rule of thumb: if a handle of type `FooHandle` has a `start()` member + * method, then it’s active from the moment that method is called. Likewise, + * `stop()` deactivates the handle again. + * + * @return True if the handle is active, false otherwise. */ virtual bool active() const noexcept = 0; @@ -60,7 +69,7 @@ public: * This function should only be used between the initialization of the * handle and the arrival of the close callback. * - * @return Non-zero if the handle is closing or closed, zero otherwise. + * @return True if the handle is closing or closed, false otherwise. */ virtual bool closing() const noexcept = 0; @@ -82,7 +91,7 @@ public: /** * @brief Checks if the given handle referenced. - * @return Non-zero if the handle referenced, zero otherwise. + * @return True if the handle referenced, false otherwise. */ virtual bool referenced() const noexcept = 0; @@ -263,7 +272,7 @@ public: * [documentation](http://docs.libuv.org/en/v1.x/loop.html#c.uv_run) * for further details. * - * @return Zero when done, non-zero in all other cases. + * @return True when done, false in all other cases. */ template bool run() noexcept { @@ -274,7 +283,7 @@ public: /** * @brief Checks if there are active resources. - * @return Non-zero if there are active resources in the loop. + * @return True if there are active resources in the loop. */ bool alive() const noexcept { return !(uv_loop_alive(loop.get()) == 0); diff --git a/src/uvw/poll.hpp b/src/uvw/poll.hpp index 1809a1ac..68fc42cc 100644 --- a/src/uvw/poll.hpp +++ b/src/uvw/poll.hpp @@ -26,6 +26,12 @@ enum class UVPollEvent: std::underlying_type_t { } + +/** + * @brief PollEvent event. + * + * It will be emitted by the PollHandle according with its functionalities. + */ struct PollEvent: Event { explicit PollEvent(Flags f) noexcept : flgs{std::move(f)} @@ -38,6 +44,16 @@ private: }; +/** + * @brief The PollHandle handle. + * + * Poll handles are used to watch file descriptors for readability, writability + * and disconnection. + * + * See the official + * [documentation](http://docs.libuv.org/en/v1.x/poll.html) + * for further details. + */ class PollHandle final: public Handle { static void startCallback(uv_poll_t *handle, int status, int events) { PollHandle &poll = *(static_cast(handle->data)); @@ -50,11 +66,20 @@ class PollHandle final: public Handle { public: using Event = details::UVPollEvent; + /** + * @brief Creates a new poll handle. + * @param args A pointer to the loop from which the handle generated. + * @return A pointer to the newly created handle. + */ template static std::shared_ptr create(Args&&... args) { return std::shared_ptr{new PollHandle{std::forward(args)...}}; } + /** + * @brief Initializes the handle. + * @return True in case of success, false otherwise. + */ bool init(int fd) { return initialize(&uv_poll_init, fd); } diff --git a/src/uvw/prepare.hpp b/src/uvw/prepare.hpp index a4bb8c00..24b4aaea 100644 --- a/src/uvw/prepare.hpp +++ b/src/uvw/prepare.hpp @@ -13,7 +13,7 @@ namespace uvw { /** - * @brief Trigger event. + * @brief PrepareEvent event. * * It will be emitted by the PrepareHandle according with its functionalities. */ diff --git a/src/uvw/request.hpp b/src/uvw/request.hpp index 4c062836..7b9133e6 100644 --- a/src/uvw/request.hpp +++ b/src/uvw/request.hpp @@ -46,11 +46,26 @@ protected: } public: + /** + * @brief Cancels a pending request. + * + * This method fails if the request is executing or has finished + * executing.
+ * It can emit an ErrorEvent event in case of errors. + * + * See the official + * [documentation](http://docs.libuv.org/en/v1.x/request.html#c.uv_cancel) + * for further details. + */ void cancel() { auto err = uv_cancel(this->template get()); if(err) { Emitter::publish(ErrorEvent{err}); } } + /** + * @brief Returns the size of the underlying request type. + * @return The size of the underlying request type. + */ std::size_t size() const noexcept { return uv_req_size(this->template get()->type); } diff --git a/src/uvw/timer.hpp b/src/uvw/timer.hpp index b70f2290..a2934413 100644 --- a/src/uvw/timer.hpp +++ b/src/uvw/timer.hpp @@ -14,7 +14,7 @@ namespace uvw { /** - * @brief Trigger event. + * @brief TimerEvent event. * * It will be emitted by the TimerHandle according with its functionalities. */