{"id":13540044,"url":"https://github.com/mitchellh/libxev","last_synced_at":"2025-05-14T02:09:10.306Z","repository":{"id":65497650,"uuid":"586344019","full_name":"mitchellh/libxev","owner":"mitchellh","description":"libxev is a cross-platform, high-performance event loop that provides abstractions for non-blocking IO, timers, events, and more and works on Linux (io_uring or epoll), macOS (kqueue), and Wasm + WASI. Available as both a Zig and C API.","archived":false,"fork":false,"pushed_at":"2025-05-08T14:21:44.000Z","size":1144,"stargazers_count":2707,"open_issues_count":38,"forks_count":114,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-05-13T13:18:34.173Z","etag":null,"topics":["async","c","epoll","io-uring","kqueue","wasi","webassembly","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitchellh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-07T19:52:16.000Z","updated_at":"2025-05-13T03:35:17.000Z","dependencies_parsed_at":"2024-01-14T05:55:20.478Z","dependency_job_id":"515c729d-73b3-4f13-b461-3a72d9eda00c","html_url":"https://github.com/mitchellh/libxev","commit_stats":{"total_commits":386,"total_committers":26,"mean_commits":"14.846153846153847","dds":"0.17098445595854928","last_synced_commit":"690c76fd792f001c5776716f1e7b04be2cc50b52"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Flibxev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Flibxev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Flibxev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Flibxev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitchellh","download_url":"https://codeload.github.com/mitchellh/libxev/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254053245,"owners_count":22006717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","c","epoll","io-uring","kqueue","wasi","webassembly","zig"],"created_at":"2024-08-01T09:01:38.371Z","updated_at":"2025-05-14T02:09:05.283Z","avatar_url":"https://github.com/mitchellh.png","language":"Zig","readme":"# libxev\n\nlibxev is a cross-platform event loop. libxev provides a unified event loop\nabstraction for non-blocking IO, timers, signals, events, and more that\nworks on macOS, Windows, Linux, and WebAssembly (browser and WASI). It is\nwritten in [Zig](https://ziglang.org/) but exports a C-compatible API (which\nfurther makes it compatible with any language out there that can communicate\nwith C APIs).\n\n**Project Status: Stable for most use cases.** libxev is in daily use by\nlarge projects such as [Ghostty](https://ghostty.org),\n[zml](https://github.com/zml/zml), and more. For most use cases, libxev\nhas been shown to be stable at scale. libxev has a broad featureset and\nthere are likely less well-used corners of the library, but for most\nuse cases libxev is already heavily used in production environments.\n\n**Why a new event loop library?** A few reasons. One, I think Zig lacks\na generalized event loop comparable to libuv in features (\"generalized\"\nbeing a key word here). Two, I wanted to build a library like this around\nthe design patterns of [io_uring](https://unixism.net/loti/what_is_io_uring.html),\neven mimicking its style on top of other OS primitives (\n[credit to this awesome blog post](https://tigerbeetle.com/blog/a-friendly-abstraction-over-iouring-and-kqueue/)).\nThree, I wanted an event loop library that could build to WebAssembly\n(both WASI and freestanding) and that didn't really fit well\ninto the goals of API style of existing libraries without bringing in\nsomething super heavy like Emscripten. The motivation for this library\nprimarily though is scratching my own itch!\n\n## Features\n\n**Cross-platform.** Linux (`io_uring` and `epoll`), macOS (`kqueue`),\nWebAssembly + WASI (`poll_oneoff`, threaded and non-threaded runtimes).\n(Windows support is planned and coming soon)\n\n**[Proactor API](https://en.wikipedia.org/wiki/Proactor_pattern).** Work\nis submitted to the libxev event loop and the caller is notified of\nwork _completion_, as opposed to work _readiness_.\n\n**Zero runtime allocations.** This helps make runtime performance more\npredictable and makes libxev well suited for embedded environments.\n\n**Timers, TCP, UDP, Files, Processes.** High-level platform-agnostic APIs for\ninteracting with timers, TCP/UDP sockets, files, processes, and more. For\nplatforms that don't support async IO, the file operations are automatically\nscheduled to a thread pool.\n\n**Generic Thread Pool (Optional).** You can create a generic thread pool,\nconfigure its resource utilization, and use this to perform custom background\ntasks. The thread pool is used by some backends to do non-blocking tasks that\ndon't have reliable non-blocking APIs (such as local file operations with\n`kqueue`). The thread pool can be shared across multiple threads and event\nloops to optimize resource utilization.\n\n**Low-level and High-Level API.** The high-level API is platform-agnostic\nbut has some  opinionated behavior and limited flexibility. The high-level\nAPI is recommended but the low-level API is always an available escape hatch.\nThe low-level API is platform-specific and provides a mechanism for libxev\nusers to squeeze out maximum performance. The low-level API is _just enough\nabstraction_ above the OS interface to make it easier to use without\nsacrificing noticable performance.\n\n**Tree Shaking (Zig).** This is a feature of Zig, but substantially benefits\nlibraries such as libxev. Zig will only include function calls and features\nthat you actually use. If you don't use a particular kind of high-level\nwatcher (such as UDP sockets), then the functionality related to that\nabstraction is not compiled into your final binary at all. This lets libxev\nsupport optional \"nice-to-have\" functionality that may be considered\n\"bloat\" in some cases, but the end user doesn't have to pay for it.\n\n**Dependency-free.** libxev has no dependencies other than the built-in\nOS APIs at runtime. The C library depends on libc. This makes it very\neasy to cross-compile.\n\n### Roadmap\n\nThere are plenty of missing features that I still want to add:\n\n  * Pipe high-level API\n  * Signal handlers\n  * Filesystem events\n  * Windows backend\n  * Freestanding WebAssembly support via an external event loop (i.e. the browser)\n\nAnd more...\n\n### Performance\n\nThere is plenty of room for performance improvements, and I want to be\nfully clear that I haven't done a lot of optimization work. Still,\nperformance is looking good. I've tried to port many of\n[libuv benchmarks](https://github.com/libuv/libuv) to use the libxev\nAPI.\n\nI won't post specific benchmark results until I have a better\nenvironment to run them in. As a _very broad generalization_,\nyou shouldn't notice a slowdown using libxev compared to other\nmajor event loops. This may differ on a feature-by-feature basis, and\nif you can show really poor performance in an issue I'm interested\nin resolving it!\n\n## Example\n\nThe example below shows an identical program written in Zig and in C\nthat uses libxev to run a single 5s timer. This is almost silly how\nsimple it is but is meant to just convey the overall feel of the library\nrather than a practical use case.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e Zig \u003c/td\u003e \u003ctd\u003e C \u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```zig\nconst xev = @import(\"xev\");\n\npub fn main() !void {\n    var loop = try xev.Loop.init(.{});\n    defer loop.deinit();\n\n    const w = try xev.Timer.init();\n    defer w.deinit();\n\n    // 5s timer\n    var c: xev.Completion = undefined;\n    w.run(\u0026loop, \u0026c, 5000, void, null, \u0026timerCallback);\n\n    try loop.run(.until_done);\n}\n\nfn timerCallback(\n    userdata: ?*void,\n    loop: *xev.Loop,\n    c: *xev.Completion,\n    result: xev.Timer.RunError!void,\n) xev.CallbackAction {\n   _ = userdata;\n   _ = loop;\n   _ = c;\n   _ = result catch unreachable;\n   return .disarm;\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```zig\n#include \u003cstddef.h\u003e\n#include \u003cstdio.h\u003e\n#include \u003cxev.h\u003e\n\nxev_cb_action timerCallback(xev_loop* loop, xev_completion* c, int result, void *userdata) {\n    return XEV_DISARM;\n}\n\nint main(void) {\n    xev_loop loop;\n    if (xev_loop_init(\u0026loop) != 0) {\n        printf(\"xev_loop_init failure\\n\");\n        return 1;\n    }\n\n    xev_watcher w;\n    if (xev_timer_init(\u0026w) != 0) {\n        printf(\"xev_timer_init failure\\n\");\n        return 1;\n    }\n\n    xev_completion c;\n    xev_timer_run(\u0026w, \u0026loop, \u0026c, 5000, NULL, \u0026timerCallback);\n\n    xev_loop_run(\u0026loop, XEV_RUN_UNTIL_DONE);\n\n    xev_timer_deinit(\u0026w);\n    xev_loop_deinit(\u0026loop);\n    return 0;\n}\n```\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Installation (Zig)\n\n**These instructions are for Zig downstream users only.** If you are\nusing the C API to libxev, see the \"Build\" section.\n\nThis package works with the Zig package manager introduced in Zig 0.11.\nCreate a `build.zig.zon` file like this:\n\n```zig\n.{\n    .name = \"my-project\",\n    .version = \"0.0.0\",\n    .dependencies = .{\n        .libxev = .{\n            .url = \"https://github.com/mitchellh/libxev/archive/\u003cgit-ref-here\u003e.tar.gz\",\n            .hash = \"12208070233b17de6be05e32af096a6760682b48598323234824def41789e993432c\",\n        },\n    },\n}\n```\n\nAnd in your `build.zig`:\n\n```zig\nconst xev = b.dependency(\"libxev\", .{ .target = target, .optimize = optimize });\nexe.addModule(\"xev\", xev.module(\"xev\"));\n```\n\n## Documentation\n\n🚧 Documentation is a work-in-progress. 🚧\n\nCurrently, documentation is available in three forms: **man pages**,\n**examples**, and **code comments.** In the future, I plan on writing detailed\nguides and API documentation in website form, but that isn't currently\navailable.\n\n### Man Pages\n\nThe man pages are relatively detailed! `xev(7)` will\ngive you a good overview of the entire library. `xev-zig(7)` and\n`xev-c(7)` will provide overviews of the Zig and C API, respectively.\nFrom there, API-specifc man pages such as `xev_loop_init(3)` are\navailable. This is the best documentation currently.\n\nThere are multiple ways to browse the man pages. The most immediately friendly\nis to just browse the raw man page sources in the `docs/` directory in\nyour web browser. The man page source is a _markdown-like_ syntax so it\nrenders _okay_ in your browser via GitHub.\n\nAnother approach is to run `zig build -Dman-pages` and the man pages\nwill be available in `zig-out`. This requires\n[scdoc](https://git.sr.ht/~sircmpwn/scdoc)\nto be installed (this is available in most package managers).\nOnce you've built the man pages, you can render them by path:\n\n```\n$ man zig-out/share/man/man7/xev.7\n```\n\nAnd the final approach is to install libxev via your favorite package\nmanager (if and when available), which should hopefully put your man pages\ninto your man path, so you can just do `man 7 xev`.\n\n### Examples\n\nThere are examples available in the `examples/` folder. The examples are\navailable in both C and Zig, and you can tell which one is which using\nthe file extension.\n\nTo build an example, use the following:\n\n```\n$ zig build -Dexample-name=_basic.zig\n...\n$ zig-out/bin/example-basic\n...\n```\n\nThe `-Dexample-name` value should be the filename including the extension.\n\n### Code Comments\n\nThe Zig code is well commented. If you're comfortable reading code comments\nyou can find a lot of insight within them. The source is in the `src/`\ndirectory.\n\n# Build\n\nBuild requires the installation of the Zig 0.14.0. libxev follows stable\nZig releases and generally does not support nightly builds. When a stable\nrelease is imminent we may have a branch that supports it.\n**libxev has no other build dependencies.**\n\nOnce installed, `zig build install` on its own will build the full library and output\na [FHS-compatible](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)\ndirectory in `zig-out`. You can customize the output directory with the\n`--prefix` flag.\n\n## Tests\n\nlibxev has a large and growing test suite. To run the tests for the current\nplatform:\n\n```sh\n$ zig build test\n...\n```\n\nThis will run all the tests for all the supported features for the current\nhost platform. For example, on Linux this will run both the full io_uring\nand epoll test suite.\n\n**You can build and run tests for other platforms** by cross-compiling the\n test executable, copying it to a target machine and executing it. For example,\n the below shows how to cross-compile and build the tests for macOS from Linux:\n\n ```sh\n $ zig build -Dtarget=aarch64-macos -Dinstall-tests\n ...\n\n $ file zig-out/bin/xev-test\n zig-out/bin/xev-test: Mach-O 64-bit arm64 executable\n ```\n\n **WASI is a special-case.** You can run tests for WASI if you have\n [wasmtime](https://wasmtime.dev/) installed:\n\n ```\n $ zig build test -Dtarget=wasm32-wasi -Dwasmtime\n ...\n ```\n","funding_links":[],"categories":["Zig","C/C++程序设计","Libraries","c","Systems Programming"],"sub_categories":["资源传输下载","Asynchronous Runtime"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitchellh%2Flibxev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitchellh%2Flibxev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitchellh%2Flibxev/lists"}