Feature highlights
Full-featured event loop backed by epoll, kqueue, IOCP, event ports.
Asynchronous TCP and UDP sockets
Asynchronous DNS resolution
Asynchronous file and file system operations
File system events
ANSI escape code controlled TTY
IPC with socket sharing, using Unix domain sockets or named pipes (Windows)
Child processes
Thread pool
Signal handling
High resolution clock
Threading and synchronization primitives
Versioning
Starting with version 1.0.0 libuv follows the semantic versioning scheme. The API change and backwards compatibility rules are those indicated by SemVer. libuv will keep a stable ABI across major releases.
The ABI/API changes can be tracked here.
Documentation
Other resources
- LXJS 2012 talk — High-level introductory talk about libuv.
- libuv-dox — Documenting types and methods of libuv, mostly by reading uv.h.
- learnuv — Learn uv for fun and profit, a self guided workshop to libuv.
These resources are not handled by libuv maintainers and might be out of date. Please verify it before opening new issues.
Downloading
libuv can be downloaded either from the GitHub repository or from the downloads site.
Before verifying the git tags or signature files, importing the relevant keys is necessary. Key IDs are listed in the MAINTAINERS file, but are also available as git blob objects for easier use.
Importing a key the usual way:
$ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059
Importing a key from a git blob object:
$ git show pubkey-saghul | gpg --import
Verifying releases
Git tags are signed with the developer’s key, they can be verified as follows:
$ git verify-tag v1.6.1
Starting with libuv 1.7.0, the tarballs stored in the downloads site are signed and an accompanying signature file sit alongside each. Once both the release tarball and the signature file are downloaded, the file can be verified as follows:
$ gpg --verify libuv-1.7.0.tar.gz.sign
Run tests:
$ (cd build && ctest -C Debug –output-on-failure)
Install with Homebrew
$ brew install --HEAD libuv
Note to OS X users:
Make sure that you specify the architecture you wish to build for in the “ARCHS” flag. You can specify more than one by delimiting with a space (e.g. “x86_64 i386”).
Install with vcpkg
$ git clone https://github.com/microsoft/vcpkg.git
$ ./bootstrap-vcpkg.bat # for powershell
$ ./bootstrap-vcpkg.sh # for bash
$ ./vcpkg install libuv
Running tests
Some tests are timing sensitive. Relaxing test timeouts may be necessary on slow or overloaded machines:
$ env UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests # 10s instead of 5s
Run one test
The list of all tests is in test/test-list.h
.
This invocation will cause the test driver to fork and execute TEST_NAME
in
a child process:
$ build/uv_run_tests_a TEST_NAME
This invocation will cause the test driver to execute the test in the same process:
$ build/uv_run_tests_a TEST_NAME TEST_NAME
Debugging tools
When running the test from within the test driver process
(build/uv_run_tests_a TEST_NAME TEST_NAME
), tools like gdb and valgrind
work normally.
When running the test from a child of the test driver process
(build/uv_run_tests_a TEST_NAME
), use these tools in a fork-aware manner.
Fork-aware gdb
Use the follow-fork-mode setting:
$ gdb --args build/uv_run_tests_a TEST_NAME
(gdb) set follow-fork-mode child
...
Fork-aware valgrind
Use the --trace-children=yes
parameter:
$ valgrind --trace-children=yes -v --tool=memcheck --leak-check=full --track-origins=yes --leak-resolution=high --show-reachable=yes --log-file=memcheck-%p.log build/uv_run_tests_a TEST_NAME
Running benchmarks
See the section on running tests.
The benchmark driver is ./uv_run_benchmarks_a
and the benchmarks are
listed in test/benchmark-list.h
.
-fno-strict-aliasing
It is recommended to turn on the -fno-strict-aliasing
compiler flag in
projects that use libuv. The use of ad hoc “inheritance” in the libuv API
may not be safe in the presence of compiler optimizations that depend on
strict aliasing.
MSVC does not have an equivalent flag but it also does not appear to need it at the time of writing (December 2019.)
z/OS Notes
z/OS compilation requires ZOSLIB to be installed. When building with [CMake][], use the flag -DZOSLIB_DIR
to specify the path to ZOSLIB:
$ (cd build && cmake .. -DBUILD_TESTING=ON -DZOSLIB_DIR=/path/to/zoslib)
$ cmake --build build
z/OS creates System V semaphores and message queues. These persist on the system after the process terminates unless the event loop is closed.
Use the ipcrm
command to manually clear up System V resources.