{"id":15502903,"url":"https://github.com/jeffzi/luamark","last_synced_at":"2025-04-22T23:15:16.649Z","repository":{"id":217012711,"uuid":"742798322","full_name":"jeffzi/luamark","owner":"jeffzi","description":"A lightweight, portable microbenchmarking library for Lua","archived":false,"fork":false,"pushed_at":"2025-04-21T20:05:56.000Z","size":114,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T23:15:11.442Z","etag":null,"topics":["benchmark-framework","lua"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/jeffzi.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}},"created_at":"2024-01-13T12:00:28.000Z","updated_at":"2025-01-05T16:58:41.000Z","dependencies_parsed_at":"2024-04-08T23:42:01.640Z","dependency_job_id":"061dfa32-f1b5-45d1-8da2-3e929730a0b5","html_url":"https://github.com/jeffzi/luamark","commit_stats":{"total_commits":95,"total_committers":2,"mean_commits":47.5,"dds":"0.021052631578947323","last_synced_commit":"3bc72160a6ef27eeeee84cf6628bc316699d7376"},"previous_names":["jeffzi/luamark"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffzi%2Fluamark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffzi%2Fluamark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffzi%2Fluamark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffzi%2Fluamark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeffzi","download_url":"https://codeload.github.com/jeffzi/luamark/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250337950,"owners_count":21414104,"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":["benchmark-framework","lua"],"created_at":"2024-10-02T09:11:31.758Z","updated_at":"2025-04-22T23:15:16.625Z","avatar_url":"https://github.com/jeffzi.png","language":"Lua","readme":"# LuaMark\n\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n[![Busted](https://github.com/jeffzi/luamark/actions/workflows/busted.yml/badge.svg)](https://github.com/jeffzi/luamark/actions/workflows/busted.yml)\n[![Luacheck](https://github.com/jeffzi/luamark/actions/workflows/luacheck.yml/badge.svg)](https://github.com/jeffzi/luamark/actions/workflows/luacheck.yml)\n[![Luarocks](https://img.shields.io/luarocks/v/jeffzi/luamark?label=Luarocks\u0026logo=Lua)](https://luarocks.org/modules/jeffzi/luamark)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nLuaMark is a lightweight, portable microbenchmarking library for the Lua programming language. It provides precise measurement of both execution time and memory usage through a simple yet powerful interface. Whether you're optimizing performance bottlenecks or validating code improvements, LuaMark offers the tools you need with minimal setup overhead.\n\n## Features\n\n- **Time and Memory Measurement**: High-precision execution timing and memory allocation tracking\n  - Time: Increase timing precision with [Chronos](https://github.com/chronos-timetravel/chronos), [LuaPosix](https://github.com/luaposix/luaposix), or [LuaSocket](https://github.com/lunarmodules/luasocket)\n  - Memory: Enhance allocation tracking accuracy using [AllocSpy](https://github.com/siffiejoe/lua-allocspy)\n- **High-Precision Time Measurement**: Measure code execution time with configurable precision through multiple clock modules\n- **Memory Usage Tracking**: Monitor memory allocation patterns and footprint of Lua functions\n- **Comprehensive Statistics**: Get detailed performance insights including minimum, maximum, mean, median, and standard deviation\n- **Zero Configuration**: Start benchmarking immediately with sensible defaults while retaining full configurability\n- **Flexible Clock Support**: Choose from multiple high-precision clock modules including [chronos](https://github.com/chronos-timetravel/chronos), [luaposix](https://github.com/luaposix/luaposix), and [LuaSocket](https://github.com/diegonehab/luasocket)\n- **Advanced Memory Tracking**: Built-in memory tracking with optional enhanced precision through [AllocSpy](https://github.com/siffiejoe/lua-allocspy)\n\n## Requirements\n\n- Lua 5.1, 5.2, 5.3, 5.4, LuaJIT 2.1 or Luau\n- Optional: [chronos](https://github.com/ldrumm/chronos), [luaposix](https://github.com/luaposix/luaposix), or [LuaSocket](https://github.com/lunarmodules/luasocket) for enhanced timing precision\n- Optional: [AllocSpy](https://github.com/siffiejoe/lua-allocspy) for enhanced memory tracking\n\n## Installation\n\nInstall LuaMark using [LuaRocks](https://luarocks.org/):\n\n```shell\nluarocks install luamark\n```\n\nAlternatively, you can manually include [luamark.lua](src/luamark.lua) in your project.\n\n## Usage\n\n### Basic Time Measurement\n\nHere's a simple example measuring factorial function performance:\n\n```lua\nlocal luamark = require(\"luamark\")\n\nfunction factorial(n)\n   if n == 0 then\n      return 1\n   else\n      return n * factorial(n - 1)\n   end\nend\n\n-- Compare different input sizes\nlocal time_stats = luamark.timeit({\n   [\"n=1\"] = function()\n      factorial(1)\n   end,\n   [\"n=15\"] = function()\n      factorial(15)\n   end,\n})\n\n-- Results can be accessed as a table\nprint(type(time_stats))  -- \"table\"\n\n-- Or displayed via string conversion\nprint(time_stats)\n-- Output:\n-- Name  Rank  Ratio  Median   Mean     Min     Max     Stddev   Rounds\n-- ----  ----  -----  ------  -------  -----  -------  --------  -------\n-- n=1   1     1.00   83ns    68.17ns  1ns    15.75us  83.98ns   1000000\n-- n=15  2     4.52   375ns   380.5ns  208ns  21.42us  202.67ns  1000000\n\n-- Get the summary as a markdown table\nlocal md = luamark.summarize(time_stats, \"markdown)\n```\n\n### Single Function Timing\n\nMeasure a single function with custom rounds:\n\n```lua\nlocal time_stats = luamark.timeit(function()\n   factorial(10)\nend, { rounds = 10 })\n\nprint(time_stats)\n-- Output: 42ns ± 23ns per round (10 rounds)\n```\n\n### Memory Usage Measurement\n\nTrack memory allocations:\n\n```lua\nlocal mem_stats = luamark.memit(function()\n   local tbl = {}\n   for i = 1, 100 do\n      tbl[i] = i\n   end\nend)\n\n-- Results can be accessed as a table\nprint(type(mem_stats))  -- \"table\"\n\n-- Or displayed via string conversion\nprint(mem_stats)\n-- Output: 2.06kB ± 0B per round (533081 rounds)\n```\n\n## Technical Details\n\n### Configuration\n\nLuaMark provides several configuration options that can be set globally:\n\n- `max_iterations`: Maximum number of iterations per round (default: 1e6)\n- `min_rounds`: Minimum number of rounds to run (default: 100)\n- `max_rounds`: Maximum number of rounds to run (default: 1e6)\n- `warmups`: Number of warmup rounds before measurement (default: 1)\n\nYou can modify these settings directly through the LuaMark instance:\n\n```lua\nlocal luamark = require(\"luamark\")\n\n-- Increase minimum rounds for more statistical reliability\nluamark.min_rounds = 1000\n\n-- Adjust warmup rounds\nluamark.warmups = 5\n```\n\n### Understanding Iterations and Rounds\n\nLuaMark uses a two-level measurement system to ensure accurate timing:\n\n#### How Measurement Works\n\n1. Each measurement consists of multiple rounds\n2. Each round runs the code multiple times (iterations)\n3. The time for each round is divided by the number of iterations to get the average execution time\n4. Statistics are computed across all rounds\n\nFor example, with 1000 iterations and 100 rounds:\n\n- Your code runs 1000 times within each round\n- This process repeats 100 times\n- Total executions = 1000 \\* 100 = 100,000 times\n\nThis approach solves several problems:\n\n- **Clock Granularity**: By running multiple iterations per round, we can measure very fast operations accurately even with low-precision clocks\n- **Statistical Reliability**: Multiple rounds provide enough data points for meaningful statistics\n- **System Variability**: The two-level structure helps filter out system noise\n\nConfiguration example:\n\n```lua\nluamark.timeit(function()\n   -- Your code here\nend, {\n   iterations = 1000,  -- Code executions per round\n   rounds = 100       -- Number of rounds\n})\n```\n\n### Clock Precision Hierarchy\n\nLuaMark automatically selects the best available clock module in this order:\n\n1. **[chronos](https://github.com/ldrumm/chronos)**\n\n   - Nanosecond precision\n   - Cross-platform compatibility\n   - Recommended for most use cases\n\n2. **[luaposix](https://github.com/luaposix/luaposix)**\n\n   - High precision on supported platforms\n   - Note: Not available on MacOS\n\n3. **[LuaSocket](https://github.com/lunarmodules/luasocket)**\n\n   - Fallback option with good precision\n   - Wide platform support\n\n4. **Standard os.clock**\n   - Default fallback\n   - Platform-dependent precision\n\n### Memory Tracking\n\nLuaMark provides built-in Lua memory monitoring and can achieve higher precision through [AllocSpy](https://github.com/siffiejoe/lua-allocspy) when available.\n\n## API Documentation\n\nFor detailed API information, please refer to the [API Documentation](docs/api.md).\n\n## Contributing\n\nContributions to LuaMark are welcome and appreciated. Whether you're fixing bugs, improving documentation, or proposing new features, your help makes LuaMark better.\n\n## License\n\nLuaMark is released under the [MIT License](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffzi%2Fluamark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffzi%2Fluamark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffzi%2Fluamark/lists"}