libuvcxx

C++ wrapper for libuv, header only.

1. Usage

Copy include into your project.
Of course, you also need to configure libuv properly.
Enjoy using it.

libuvcxx supports single header file usage. You can find uvcxx-single.h in the release packages.

#include <uvcxx.h>

void detach_work() {
    // uv::timer_t()      // Create handle
    // .start(1000, 1000) // Start timer
    // .detach()          // Detached handle won't be implicitly closed
    // .call(...)         // Set callback function
    uv::timer_t().start(100, 1).detach().call([]() {
        std::cout << "Hello,";
        // Tell the associated handle to close
        throw uvcxx::close_handle();
    });

    // Classic implementation
    uv::timer_t timer;
    timer.start(200, 1).call([=]() mutable {
        std::cout << " World!" << std::endl;
        timer.close();  // Capture timer in callback function is safe ^_^.
    });
    timer.detach();
    // If detach is not called, the temporary timer will be automatically closed.
}

int main() {
    detach_work();
    return uv::default_loop().run();
}

The data field for context has already been occupied. Please note that this field should not be used anymore.

No explicit close operation is required, except when the handle is running. The handle can continue to work without any external references, so that explicit `close' is needed at this time.

See lifecycle.md for more details.

Remember, it is always a good practice to explicitly call close at any time, unless you are very clear about the lifecycle of the handle.

2. Compatibility

libuvcxx requires at least C++11 and is also compatible with the new features in C++14 and C++17.

Tested and passed in gcc 4.8.5 with libuv v1.44.2 on CentOS7.

libuvcxx can be compatible with libuv: >= 1.0.0, <= 1.48.0. Provided by test_libuv.sh.

Notice: As the development proceeds, compatibility may change with new features.

libuvcxx covers [100%] all 306 APIs described in the libuv doc. Provided by libuv_api_coverage.py.

See coverage.md for more details.

3. Schedule

More examples and documentation are pending to be added.
As well as higher-level encapsulations for some common usage scenarios.

4. Exception

libuvcxx uses exception to handle exceptions.

Most interfaces that don't often encounter errors will throw an uvcxx::errcode exception upon failure. This type of exception is thrown to facilitate the flexible use of interfaces in promise or callback contexts.

Certain interfaces that frequently encounter errors will not throw exceptions. In such cases, the success of the interface call should be judged by the return value, for example, uv::spawn.

If you're not sure whether an interface will throw an exception, please directly refer to the implementation code of the corresponding interface. After all, we are an open-source, header-only library.

You can use the macro definition UVCXX_NO_EXCEPTION before #include <uvcxx.h> to prevent interfaces from throwing exceptions. However, in the current version, exceptions are still used to handle some transactions. Future versions may consider finding suitable ways to completely eliminate the use of exceptions.

5. Adjusted API

Most APIs have been changed from uv_xxx to uv::xxx, and are placed in the necessary C++ classes according to their types.

Such as

• uv_handle_t -> uv::handle_t
• uv_fs_open -> uv::fs::open
• uv_default_loop -> uv::default_loop
• uv_close -> uv::handle_t::close .

However, some APIs still cannot be fully migrated to C++ with consistent naming, so the following lists the interface names with obvious differences (this may not cover all cases).

• uv_fs_get_type -> uv::fs_t::fs_type
• uv_read_start -> uv::stream_t::alloc + uv::stream_t::read_start
• uv_os_environ -> uv::os::get_environ