diff --git a/docs/doxy.in b/docs/doxy.in index 06655e62..886d79e3 100644 --- a/docs/doxy.in +++ b/docs/doxy.in @@ -415,7 +415,7 @@ EXTRACT_ALL = NO # be included in the documentation. # The default value is: NO. -EXTRACT_PRIVATE = YES +EXTRACT_PRIVATE = NO # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. diff --git a/src/uvw/lib.hpp b/src/uvw/lib.hpp index 4c74996f..eea664bb 100644 --- a/src/uvw/lib.hpp +++ b/src/uvw/lib.hpp @@ -21,6 +21,12 @@ template struct IsFunc: std::true_type { }; } +/** + * @brief The SharedLib class. + * + * `uvw` provides cross platform utilities for loading shared libraries and + * retrieving symbols from them, by means of the API offered by libuv. + */ class SharedLib final { explicit SharedLib(std::shared_ptr ref, std::string filename) noexcept : pLoop{std::move(ref)}, @@ -30,6 +36,15 @@ class SharedLib final { } public: + /** + * @brief Creates a new shared library object. + * @param args + * + * * A pointer to the loop from which the handle generated. + * * The filename of the library in UTF8. + * + * @return A pointer to the newly created handle. + */ template static std::shared_ptr create(Args&&... args) noexcept { return std::shared_ptr{new SharedLib{std::forward(args)...}}; @@ -45,8 +60,21 @@ public: SharedLib& operator=(const SharedLib &) = delete; SharedLib& operator=(SharedLib &&) = delete; + /** + * @brief Checks if the library has been correctly opened. + * @return True if the library is opened, false otherwise. + */ explicit operator bool() const noexcept { return !opened; } + /** + * @brief Retrieves a data pointer from a dynamic library. + * + * `F` shall be a valid function type (as an example, `void(int)`).
+ * It is legal for a symbol to map to `nullptr`. + * + * @param name The symbol to be retrieved. + * @return A valid function pointer in case of success, `nullptr` otherwise. + */ template F * sym(std::string name) { static_assert(details::IsFunc::value, "!"); @@ -56,10 +84,18 @@ public: return func; } + /** + * @brief Returns the last error message, if any. + * @return The last error message, if any. + */ const char * error() const noexcept { return uv_dlerror(&lib); } + /** + * @brief Gets the loop from which the object was originated. + * @return A reference to a loop instance. + */ Loop& loop() const noexcept { return *pLoop; } private: diff --git a/src/uvw/pipe.hpp b/src/uvw/pipe.hpp index 7fe49314..8c22cf87 100644 --- a/src/uvw/pipe.hpp +++ b/src/uvw/pipe.hpp @@ -29,29 +29,73 @@ enum class UVHandleType: std::underlying_type_t { } +/** + * @brief The PipeHandle handle. + * + * Pipe handles provide an abstraction over local domain sockets on Unix and + * named pipes on Windows. + */ class PipeHandle final: public StreamHandle { - using StreamHandle::StreamHandle; + explicit PipeHandle(std::shared_ptr ref, bool pass = false) + : StreamHandle{std::move(ref)}, ipc{pass} + { } public: using Pending = details::UVHandleType; + /** + * @brief Creates a new poll handle. + * @param args + * + * * A pointer to the loop from which the handle generated. + * * An optional boolean value (_ipc_) that indicates if this pipe will be + * used for handle passing between processes. + * + * @return A pointer to the newly created handle. + */ template static std::shared_ptr create(Args&&... args) { return std::shared_ptr{new PipeHandle{std::forward(args)...}}; } - bool init(bool ipc = false) { + /** + * @brief Initializes the handle. + * @return True in case of success, false otherwise. + */ + bool init() { return initialize(&uv_pipe_init, ipc); } + /** + * @brief Opens an existing file descriptor or handle as a pipe. + * + * The passed file descriptor or handle is not checked for its type, but + * it’s required that it represents a valid pipe. + * + * @param file A valid file handle (either a file descriptor or a handle). + */ void open(FileHandle file) { invoke(&uv_pipe_open, get(), file); } + /** + * @brief bind Binds the pipe to a file path (Unix) or a name (Windows). + * + * Paths on Unix get truncated typically between 92 and 108 bytes. + * + * @param name A valid file path. + */ void bind(std::string name) { invoke(&uv_pipe_bind, get(), name.data()); } + /** + * @brief Connects to the Unix domain socket or the named pipe. + * + * Paths on Unix get truncated typically between 92 and 108 bytes. + * + * @param name A valid domain socket or named pipe. + */ void connect(std::string name) { auto listener = [ptr = shared_from_this()](const auto &event, details::ConnectReq &) { ptr->publish(event); @@ -63,22 +107,56 @@ public: connect->connect(&uv_pipe_connect, get(), name.data()); } + /** + * @brief Gets the name of the Unix domain socket or the named pipe. + * @return The name of the Unix domain socket or the named pipe. + */ std::string sock() const noexcept { return details::path(&uv_pipe_getsockname, get()); } + /** + * @brief Gets the name of the Unix domain socket or the named pipe to which + * the handle is connected. + * @return The name of the Unix domain socket or the named pipe to which + * the handle is connected. + */ std::string peer() const noexcept { return details::path(&uv_pipe_getpeername, get()); } + /** + * @brief Sets the number of pending pipe this instance can handle. + * + * This method can be used to set the number of pending pipe this instance + * handles when the pipe server is waiting for connections.
+ * Note that this setting applies to Windows only. + * + * @param count The number of accepted pending pipe. + */ void pending(int count) noexcept { uv_pipe_pending_instances(get(), count); } + /** + * @brief Gets the number of pending pipe this instance can handle. + * @return The number of pending pipe this instance can handle. + */ int pending() noexcept { return uv_pipe_pending_count(get()); } + /** + * @brief Used to receive handles over IPC pipes. + * + * Steps to be done: + * + * * Call `pending()`, if it’s greater than zero then proceed. + * * Initialize a handle of the given type, returned by `receive()`. + * * Call `accept(pipe, handle)`. + * + * @return + */ Pending receive() noexcept { auto type = uv_pipe_pending_type(get()); @@ -93,6 +171,9 @@ public: return Pending::UNKNOWN; } } + +private: + bool ipc; }; diff --git a/src/uvw/util.hpp b/src/uvw/util.hpp index 10b96dcc..7932f77f 100644 --- a/src/uvw/util.hpp +++ b/src/uvw/util.hpp @@ -12,6 +12,16 @@ namespace uvw { +/** + * @brief Utility class to handle flags. + * + * This class can be used to handle flags of a same enumeration type.
+ * It is meant to be used as an argument for functions and member methods and + * as part of events.
+ * `Flags` objects can be easily _or-ed_ and _and-ed_ with other instances of + * the same type or with instances of the type `E` (that is, the actual flag + * type), thus converted to the underlying type when needed. + */ template class Flags final { using InnerType = std::underlying_type_t; @@ -21,8 +31,22 @@ class Flags final { public: using Type = InnerType; + /** + * @brief Constructs a Flags object from a value of the enum `E`. + * @param flag An value of the enum `E`. + */ constexpr Flags(E flag) noexcept: flags{toInnerType(flag)} { } + + /** + * @brief Constructs a Flags object from an instance of the underlying type + * of the enum `E`. + * @param f An instance of the underlying type of the enum `E`. + */ constexpr Flags(Type f): flags{f} { } + + /** + * @brief Constructs an uninitialized Flags object. + */ constexpr Flags(): flags{} { } constexpr Flags(const Flags &f) noexcept: flags{f.flags} { } @@ -40,13 +64,44 @@ public: return *this; } + /** + * @brief Or operator. + * @param f A valid instance of Flags. + * @return This instance _or-ed_ with `f`. + */ constexpr Flags operator|(const Flags &f) const noexcept { return Flags(flags | f.flags); } + + /** + * @brief Or operator. + * @param flag A value of the enum `E`. + * @return This instance _or-ed_ with `flag`. + */ constexpr Flags operator|(E flag) const noexcept { return Flags(flags | toInnerType(flag)); } + /** + * @brief And operator. + * @param f A valid instance of Flags. + * @return This instance _and-ed_ with `f`. + */ constexpr Flags operator&(const Flags &f) const noexcept { return Flags(flags & f.flags); } + + /** + * @brief And operator. + * @param flag A value of the enum `E`. + * @return This instance _and-ed_ with `flag`. + */ constexpr Flags operator&(E flag) const noexcept { return Flags(flags & toInnerType(flag)); } + /** + * @brief Checks if this instance is initialized. + * @return False if it's uninitialized, true otherwise. + */ explicit constexpr operator bool() const noexcept { return !(flags == InnerType{}); } + + /** + * @brief Casts the instance to the underlying type of `E`. + * @return An integral representation of the contained flags. + */ constexpr operator Type() const noexcept { return flags; } private: @@ -54,10 +109,32 @@ private: }; +/** + * @brief Wrapper for underlying library's types. + * + * In particular, It is used for: + * + * * FileHandle (that is an alias for `UVTypeWrapper`) + * * OSSocketHandle (that is an alias for `UVTypeWrapper`) + * * OSFileDescriptor (that is an alias for `UVTypeWrapper`) + * + * It can be bound to each value of type `T` and it will be implicitly converted + * to the underlying type when needed. + */ template struct UVTypeWrapper { using Type = T; + + /** + * @brief Constructs a new instance of the wrapper. + * @param val The value to be stored. + */ constexpr UVTypeWrapper(Type val): value{val} { } + + /** + * @brief Cast operator to the underlying type. + * @return The stored value. + */ constexpr operator Type() const noexcept { return value; } private: const Type value; @@ -69,12 +146,28 @@ using OSSocketHandle = UVTypeWrapper; using OSFileDescriptor = UVTypeWrapper; -static constexpr auto STDIN = FileHandle{0}; -static constexpr auto STDOUT = FileHandle{1}; -static constexpr auto STDERR = FileHandle{2}; - - +/** + * @brief Address representation. + * + * Pair alias (see Boost/Mutant idiom) used to pack together an ip and a + * port.
+ * Instead of `first` and `second`, the two parameters are named: + * + * * `ip`, that is of type `std::string` + * * `port`, that is of type `unsigned int` + */ struct Addr { std::string ip; unsigned int port; }; + +/** + * @brief Windows size representation. + * + * Pair alias (see Boost/Mutant idiom) used to pack together a width and a + * height.
+ * Instead of `first` and `second`, the two parameters are named: + * + * * `width`, that is of type `int` + * * `height`, that is of type `int` + */ struct WinSize { int width; int height; };