Libuv -- Getting Started

Libuv and io_uring

https://github.com/libuv/libuv/pull/3952

Projects that use libuv

• Nodejs
• Neovim embeds libuv inside. Checkout this example.
• Python uvloop and many ASGI web server uses uvloop instead of asyncio.

An interesting thing is Redis has its own event loop implementation, and refused to add libuv support.

Build libuv

Follow the official documentation https://github.com/libuv/libuv#build-instructions

mkdir -p build
cd build && cmake .. -DBUILD_TESTING=ON
cd ..
cmake --build build

If you need to build the debug version and see the full compilation commands, change above line to

cmake .. -DBUILD_TESTING=ON -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_FLAGS_DEBUG="-g -O0" -DCMAKE_CXX_FLAGS_DEBUG="-g -O0"

Remember to do a make clean in the build folder first.

Build an example in the docs folder

We use tcp-echo-server as an example, and suppose we already built libuv in the above step.

Dynamic linking

gcc docs/code/tcp-echo-server/main.c -I include/ -L ./build -luv -rpath /Users/xiongding/code/libuv/build/

It generates a a.out file. Inspecting it gives

$ otool -L a.out
a.out:
        @rpath/libuv.1.dylib (compatibility version 1.0.0, current version 1.0.0)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1319.100.3)

You can add -g -O0 to the compilation command if you want to debug.

static linking

gcc docs/code/tcp-echo-server/main.c -I include/ build/libuv.a

# verify binary
$ otool -L a.out
a.out:
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1319.100.3)

Run it

In one terminal, run ./a.out. In another terminal,

$ nc localhost 7000
adfas
adfas
dfasdfa
dfasdfa
^C

Anything you typed will be echoed back.

Have fun inside gdb

Macbook M1 does not support gdb, so I can only use lldb. Before we start, make sure you build both libuv and the example using -g -O0.

$ lldb a.out
(lldb) b main
Breakpoint 1: where = a.out`main + 40 at main.c:73:12, address = 0x0000000100002c94
(lldb) r
Process 29843 launched: '/Users/xiongding/code/libuv/a.out' (arm64)
Process 29843 stopped
* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
    frame #0: 0x0000000100002c94 a.out`main at main.c:73:12
   70   }
   71
   72   int main() {
-> 73       loop = uv_default_loop();
   74
   75       uv_tcp_t server;
   76       uv_tcp_init(loop, &server);
Target 0: (a.out) stopped.
(lldb)

Having fun with digging around!

Idle event

I find the idle concept is a little hard to grasp the first time I read it. And it turns out that it is not only me! See issue-1035. Basically, the semantics of idle is similar to a 0-timeout repeating timer. Also idle is used to implement setImmediate.

Together with idle, there are other two watchers that have the exact same definition: prepare and check. We can think of prepare as watcher needs to be processed before IO callbacks, and check is watcher processed after IO callbacks. The macro definition for these three types are UV_LOOP_WATCHER_DEFINE.