luo980/uvw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
Michele Caini 2016-08-02 15:48:45 +02:00
parent 0ab9572749
commit 21b22977d5
9 changed files with 190 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/uvw/async.hpp
View File

@ -13,7 +13,7 @@ namespace uvw {
/**
* @brief Trigger event.
* @brief AsyncEvent event.
*
* It will be emitted by the AsyncHandle according with its functionalities.
*/

2
src/uvw/check.hpp
View File

@ -13,7 +13,7 @@ namespace uvw {
/**
* @brief Trigger event.
* @brief CheckEvent event.
*
* It will be emitted by the CheckHandle according with its functionalities.
*/

126
src/uvw/handle.hpp
View File

@ -11,9 +11,19 @@
namespace uvw {
/**
* @brief CloseEvent event.
*
* It will be emitted by the handles according with their functionalities.
*/
struct CloseEvent: Event<CloseEvent> { };
/**
* @brief Handle base class.
*
* Base type for all `uvw` handle types.
*/
template<typename T, typename U>
class Handle: public BaseHandle, public Resource<T, U>
{
@ -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<uv_handle_t>()) == 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<uv_handle_t>()) == 0);
}
/**
* @brief Request handle to be closed.
*
* This **must** be called on each handle before memory is released.<br/>
* In-progress requests are cancelled and this can result in an ErrorEvent
* emitted.
*/
void close() noexcept override {
if(!closing()) {
uv_close(this->template get<uv_handle_t>(), &Handle<T, U>::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<uv_handle_t>());
}
/**
* @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<uv_handle_t>());
}
/**
* @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<uv_handle_t>()) == 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<uv_handle_t>()->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.<br/>
* This function works for TcpHandle, PipeHandle and UDPHandle handles on
* Unix and for TcpHandle and UDPHandle handles on Windows.<br/>
* 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.<br/>
* This function works for TcpHandle, PipeHandle and UDPHandle handles on
* Unix and for TcpHandle and UDPHandle handles on Windows.<br/>
* 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.<br/>
* This function works for TcpHandle, PipeHandle and UDPHandle handles on
* Unix and for TcpHandle and UDPHandle handles on Windows.<br/>
* 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.<br/>
* This function works for TcpHandle, PipeHandle and UDPHandle handles on
* Unix and for TcpHandle and UDPHandle handles on Windows.<br/>
* 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.<br/>
* 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<uv_handle_t>(), &fd);

2
src/uvw/idle.hpp
View File

@ -13,7 +13,7 @@ namespace uvw {
/**
* @brief Trigger event.
* @brief IdleEvent event.
*
* It will be emitted by the IdleHandle according with its functionalities.
*/

29
src/uvw/loop.hpp
View File

@ -43,14 +43,23 @@ enum class UVRunMode: std::underlying_type_t<uv_run_mode> {
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.<br/>
* 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<Mode mode = Mode::DEFAULT>
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);

25
src/uvw/poll.hpp
View File

@ -26,6 +26,12 @@ enum class UVPollEvent: std::underlying_type_t<uv_poll_event> {
}
/**
* @brief PollEvent event.
*
* It will be emitted by the PollHandle according with its functionalities.
*/
struct PollEvent: Event<PollEvent> {
explicit PollEvent(Flags<details::UVPollEvent> 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<PollHandle, uv_poll_t> {
static void startCallback(uv_poll_t *handle, int status, int events) {
PollHandle &poll = *(static_cast<PollHandle*>(handle->data));
@ -50,11 +66,20 @@ class PollHandle final: public Handle<PollHandle, uv_poll_t> {
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<typename... Args>
static std::shared_ptr<PollHandle> create(Args&&... args) {
return std::shared_ptr<PollHandle>{new PollHandle{std::forward<Args>(args)...}};
}
/**
* @brief Initializes the handle.
* @return True in case of success, false otherwise.
*/
bool init(int fd) {
return initialize<uv_poll_t>(&uv_poll_init, fd);
}

2
src/uvw/prepare.hpp
View File

@ -13,7 +13,7 @@ namespace uvw {
/**
* @brief Trigger event.
* @brief PrepareEvent event.
*
* It will be emitted by the PrepareHandle according with its functionalities.
*/

15
src/uvw/request.hpp
View File

@ -46,11 +46,26 @@ protected:
}
public:
/**
* @brief Cancels a pending request.
*
* This method fails if the request is executing or has finished
* executing.<br/>
* 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<uv_req_t>());
if(err) { Emitter<T>::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<uv_req_t>()->type);
}

2
src/uvw/timer.hpp
View File

@ -14,7 +14,7 @@ namespace uvw {
/**
* @brief Trigger event.
* @brief TimerEvent event.
*
* It will be emitted by the TimerHandle according with its functionalities.
*/