{"id":14990800,"url":"https://github.com/hendriknielaender/zbench","last_synced_at":"2025-04-05T20:01:51.797Z","repository":{"id":170277434,"uuid":"645371375","full_name":"hendriknielaender/zBench","owner":"hendriknielaender","description":"📊 zig benchmark","archived":false,"fork":false,"pushed_at":"2025-04-01T15:29:15.000Z","size":3712,"stargazers_count":120,"open_issues_count":12,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T13:07:16.221Z","etag":null,"topics":["bench","benchmark","benchmarking","performance","stdout","testing","zig","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"https://hendriknielaender.github.io/zBench/","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/hendriknielaender.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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}},"created_at":"2023-05-25T13:57:54.000Z","updated_at":"2025-04-01T15:26:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"8bcc01ad-da62-4284-82ca-948d7125af31","html_url":"https://github.com/hendriknielaender/zBench","commit_stats":null,"previous_names":["hendriknielaender/zbench"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriknielaender%2FzBench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriknielaender%2FzBench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriknielaender%2FzBench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriknielaender%2FzBench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hendriknielaender","download_url":"https://codeload.github.com/hendriknielaender/zBench/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247393547,"owners_count":20931811,"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":["bench","benchmark","benchmarking","performance","stdout","testing","zig","zig-package","ziglang"],"created_at":"2024-09-24T14:20:52.680Z","updated_at":"2025-04-05T20:01:51.787Z","avatar_url":"https://github.com/hendriknielaender.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ zBench - A Zig Benchmarking Library\n\n[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/hendriknielaender/zbench/blob/HEAD/LICENSE)\n![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/hendriknielaender/zbench)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/hendriknielaender/zbench/blob/HEAD/CONTRIBUTING.md)\n\u003cimg src=\"logo.png\" alt=\"zBench logo\" align=\"right\" width=\"20%\"/\u003e\n\nzBench is a benchmarking library for the Zig programming language. It is designed to provide easy-to-use functionality to measure and compare the performance of your code.\n\n## Content\n\n* [Installation](docs/install.md)\n* [Usage](#usage)\n* [Configuration](#configuration)\n  * [Compatibility Notes](#compatibility-notes)\n  * [Reporting Benchmarks](#reporting-benchmarks)\n  * [Running zBench Examples](#running-zbench-examples)\n  * [Troubleshooting](#troubleshooting)\n* [Contributing](#contributing)\n* [License](#license)\n\n## Installation\n\nFor installation instructions, please refer to the [documentation](docs/install.md).\n\n## Usage\n\nCreate a new benchmark function in your Zig code. This function takes a single argument of type `std.mem.Allocator` and runs the code you wish to benchmark.\n\n```zig\nfn benchmarkMyFunction(allocator: std.mem.Allocator) void {\n    // Code to benchmark here\n}\n```\n\nYou can then run your benchmarks in a test:\n\n```zig\ntest \"bench test\" {\n    var bench = zbench.Benchmark.init(std.testing.allocator, .{});\n    defer bench.deinit();\n    try bench.add(\"My Benchmark\", myBenchmark, .{});\n    try bench.run(std.io.getStdOut().writer());\n}\n```\n\n## Configuration\n\nTo customize your benchmark runs, zBench provides a `Config` struct that allows you to specify several options:\n\n```zig\npub const Config = struct {\n    iterations: u16 = 0,\n    max_iterations: u16 = 16384,\n    time_budget_ns: u64 = 2e9, // 2 seconds\n    hooks: Hooks = .{},\n    track_allocations: bool = false, \n    use_shuffling_allocator: bool = false,\n};\n```\n\n* `iterations`: The number of iterations the benchmark has been run. This field is usually managed by zBench itself.\n* `max_iterations`: Set the maximum number of iterations for a benchmark. Useful for controlling long-running benchmarks.\n* `time_budget_ns`: Define a time budget for the benchmark in nanoseconds. Helps in limiting the total execution time of the benchmark.\n* `hooks`: Set `before_all`, `after_all`, `before_each`, and `after_each` hooks to function pointers.\n* `track_allocations`: Boolean to enable or disable tracking memory allocations during the benchmark.\n* `use_shuffling_allocator`: an experimental `ShufflingAllocator`. This allocator randomizes memory allocation patterns, which can be useful for identifying potential memory-related bugs and reducing bias caused by predictable memory layouts during benchmarking.\n\n**Important Note:** The `ShufflingAllocator` will likely introduce *some* performance overhead compared to a standard allocator. The extent of the overhead is currently not specified! Consider this when interpreting your benchmark results.\n\n### Compatibility Notes\n\n#### Zig version\n\nZig is in active development, and its APIs can change frequently. The main branch of this project now targets the latest Zig master build to take advantage of new features and improvements. For users who prefer the stability of official releases, dedicated branches are maintained for older Zig versions (e.g., zig-0.13.0, zig-0.12.0, etc.). This ensures you can choose the branch that best fits your stability and feature requirements.\n\n#### Performance Note\n\nIt's important to acknowledge that a no-op time of ca. 15 ns (or more) is expected and is not an issue with zBench itself (see also [#77](https://github.com/hendriknielaender/zBench/issues/77)). This does not reflect an inefficiency in the benchmarking process.\n\n### Reporting Benchmarks\n\nzBench provides a comprehensive report for each benchmark run. It includes the total operations performed, the average, min, and max durations of operations, and the percentile distribution (p75, p99, p995) of operation durations.\n\n```shell\nbenchmark              runs     time (avg ± σ)         (min ... max)                p75        p99        p995\n---------------------------------------------------------------------------------------------------------------\nbenchmarkMyFunction    1000     1200ms ± 10ms          (100ms ... 2000ms)           1100ms     1900ms     1950ms\n```\n\nThis example report indicates that the benchmark \"benchmarkMyFunction\" ran with an average of 1200 ms per execution and a standard deviation of 10 ms.\nThe minimum and maximum execution times were 100 ms and 2000 ms, respectively. The 75th, 99th and 99.5th percentiles of execution times were 1100 ms, 1900 ms, and 1950 ms, respectively.\n\n### Running zBench Examples\n\nYou can build all examples with the following command:\n\n```shell\nzig build examples\n```\n\nExecutables can then be found in `./zig-out/bin` by default.\n\n### Troubleshooting\n\n* If Zig doesn't detect changes in a dependency, clear the project's `zig-cache` folder and `~/.cache/zig`.\n* [Non-ASCII characters not printed correctly on Windows](docs/advanced.md)\n\n## Contributing\n\nThe main purpose of this repository is to continue to evolve zBench, making it faster and more efficient. We are grateful to the community for contributing bugfixes and improvements. Read below to learn how you help improve zBench.\n\n### Contributing Guide\n\nRead our [contributing guide](CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to zBench.\n\n### License\n\nzBench is [MIT licensed](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhendriknielaender%2Fzbench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhendriknielaender%2Fzbench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhendriknielaender%2Fzbench/lists"}