https://github.com/levalup/libuvcxx
Single header C++ wrapper for libuv
https://github.com/levalup/libuvcxx
cpp11 cpp14 cpp17 libuv libuv-bindings
Last synced: 10 months ago
JSON representation
Single header C++ wrapper for libuv
- Host: GitHub
- URL: https://github.com/levalup/libuvcxx
- Owner: levalup
- License: mit
- Created: 2024-05-30T09:19:55.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-07-26T13:31:25.000Z (almost 2 years ago)
- Last Synced: 2025-04-10T01:44:38.663Z (about 1 year ago)
- Topics: cpp11, cpp14, cpp17, libuv, libuv-bindings
- Language: C++
- Homepage:
- Size: 359 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# libuvcxx
[](
LICENSE)
[](
https://github.com/libuv/libuv)
[](
https://cmake.org)
[](
https://en.cppreference.com/w/cpp/11)
[](
https://en.cppreference.com/w/cpp/14)
[](
https://en.cppreference.com/w/cpp/17)
[](
https://github.com/levalup/libuvcxx/actions/workflows/build.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/build-classic.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/build-gcc.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/build-gcc-std.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/build-macos.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/build-mingw.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/build-msvc-std.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/single-header.yml)
[](
https://github.com/levalup/libuvcxx/actions/workflows/release.yml)
> 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](https://github.com/levalup/libuvcxx/releases).
```cpp
#include
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](docs/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](scripts/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](https://docs.libuv.org/en/v1.x/).
Provided by [libuv_api_coverage.py](scripts/libuv_api_coverage.py).
See [coverage.md](docs/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 ` 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`