{"id":18016562,"url":"https://github.com/webassembly/wasi-clocks","last_synced_at":"2025-08-12T14:39:53.373Z","repository":{"id":38983979,"uuid":"261895493","full_name":"WebAssembly/wasi-clocks","owner":"WebAssembly","description":"Clocks API for WASI","archived":false,"fork":false,"pushed_at":"2025-06-12T21:17:35.000Z","size":955,"stargazers_count":53,"open_issues_count":17,"forks_count":16,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-08-02T17:57:16.734Z","etag":null,"topics":["proposal","wasi"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebAssembly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-05-06T22:48:07.000Z","updated_at":"2025-08-01T20:55:50.000Z","dependencies_parsed_at":"2023-02-15T17:30:38.123Z","dependency_job_id":"e0e180bd-773a-453a-aad5-8e07d94c4db4","html_url":"https://github.com/WebAssembly/wasi-clocks","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/WebAssembly/wasi-clocks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-clocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-clocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-clocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-clocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebAssembly","download_url":"https://codeload.github.com/WebAssembly/wasi-clocks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-clocks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270077967,"owners_count":24523298,"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","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["proposal","wasi"],"created_at":"2024-10-30T04:18:28.444Z","updated_at":"2025-08-12T14:39:53.333Z","avatar_url":"https://github.com/WebAssembly.png","language":null,"readme":"# WASI Clocks\n\nA proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.\n\n### Current Phase\n\nWASI-clocks is currently in [Phase 3].\n\n[Phase 3]: https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-3---implementation-phase-cg--wg\n\n### Champions\n\n- Dan Gohman\n\n### Portability Criteria\n\nWASI clocks must have host implementations which can pass the testsuite\non at least Windows, macOS, and Linux.\n\nWASI clocks must have at least two complete independent implementations.\n\n## Table of Contents\n\n- [WASI Clocks](#wasi-clocks)\n    - [Current Phase](#current-phase)\n    - [Champions](#champions)\n    - [Portability Criteria](#portability-criteria)\n  - [Table of Contents](#table-of-contents)\n    - [Introduction](#introduction)\n    - [Goals](#goals)\n    - [Non-goals](#non-goals)\n    - [API walk-through](#api-walk-through)\n      - [Measuring elapsed time](#measuring-elapsed-time)\n      - [Telling the current human time:](#telling-the-current-human-time)\n      - [Retrieving the timezone:](#retrieving-the-timezone)\n    - [Detailed design discussion](#detailed-design-discussion)\n    - [What should the type of a timestamp be?](#what-should-the-type-of-a-timestamp-be)\n    - [Considered alternatives](#considered-alternatives)\n      - [Per-process and per-thread clocks](#per-process-and-per-thread-clocks)\n    - [Stakeholder Interest \\\u0026 Feedback](#stakeholder-interest--feedback)\n    - [References \\\u0026 acknowledgements](#references--acknowledgements)\n    - [Development](#development)\n      - [Generating imports.md](#generating-importsmd)\n\n### Introduction\n\nWASI Clocks is a WASI API for reading the current time and measuring elapsed\ntime.\n\nUnlike many clock APIs, WASI Clocks is capability-oriented. Instead\nof having functions that implicitly reference a clock, WASI Clocks' APIs are\npassed a clock handle.\n\n### Goals\n\nThe primary goal of WASI Clocks is to allow users to use WASI programs to\nread the current time and to measure elapsed time.\n\n### Non-goals\n\nWASI Clocks is not aiming to cover date formatting, or modifying the time of a clock.\n\n### API walk-through\n\n#### Measuring elapsed time\n\nThe monotonic clock APIs can be used to measure the elapsed time of a region of code:\n\n```wit\ndefault-monotonic-clock: monotonic-clock\n```\n\n```rust\n   let start: Instant = monotonic_clock::now(clock);\n\n   // some stuff\n\n   let stop: Instant = monotonic_clock::now(clock);\n\n   let elapsed: Instant = stop - start;\n```\n\n\n#### Telling the current human time:\n\n```rust\n    let the_current_time = wall_clock::now();\n\n    println!(\"it has been {} seconds and {} nanoseconds since the Unix epoch!\", the_current_time.seconds, the_current_time.nanoseconds);\n```\n\n#### Retrieving the timezone:\n\n```rust\n    let datetime: Datetime = wall_clock::now();\n\n    let timezone_display: TimezoneDisplay = timezone::display(datetime);\n\n    println!(\"the timezone is {}\", timezone_display.name);\n```\n\n### Detailed design discussion\n\n### What should the type of a timestamp be?\n\nIn POSIX, `clock_gettime` uses a single `timespec` type to represent timestamps\nfrom all clocks, with two fields: seconds and nanoseconds. However, in applications\nthat just need to measure elapsed time, and don't need to care about wall clock\ntime, working with seconds and nanoseconds as separate fields adds extra code size\nand complexity. For these use cases, a single 64-bit nanoseconds value, which can\nmeasure up to about 584 years, is sufficient and simpler.\n\nFor wall clock time, it's still useful to have both seconds and nanoseconds, both\nto be able to represent dates in the far future, and to reflect the fact that\ncode working with wall clock time will often want to treat seconds and fractions\nof seconds differently.\n\nAnd so, this API uses different data types for different types of clocks.\n\n### Considered alternatives\n\n#### Per-process and per-thread clocks\n\nWASI preview1 included two clocks which measured the CPU time of the current process and the current thread, respectively. These clocks are difficult to implement efficiently in WASI implementations that have multiple wasm instances in the same host process, so they've been omitted from this API.\n\nWasi-libc has support for emulating these clocks, by using the monotonic clock instead, which isn't a technically precise replacement, but is enough to ensure minimal compatibility with existing code.\n\n### Stakeholder Interest \u0026 Feedback\n\nTODO before entering Phase 3.\n\nPreview1 has monotonic and wall clock functions, and they're widely exposed in toolchains.\n\n### References \u0026 acknowledgements\n\nMany thanks for valuable feedback and advice from:\n\n- [Person 1]\n- [Person 2]\n- [etc.]\n\n### Development\n\n#### Generating imports.md\n\nThe file `imports.md` is generated using [wit-bindgen](https://github.com/bytecodealliance/wit-bindgen).\n\n```bash\nwit-bindgen markdown wit --html-in-md --features clocks-timezone\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebassembly%2Fwasi-clocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebassembly%2Fwasi-clocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebassembly%2Fwasi-clocks/lists"}