mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-16 22:01:22 +01:00
feat(clock): the master clock
Every record in a session is stamped on one monotonic clock: `mach_absolute_time` on macOS and `QueryPerformanceCounter` on Windows, behind a `platform` facade with a third `unsupported` host that builds anywhere. Anchors pair that clock with the wall clock, a map interpolates between them, and a jump detector notices sleep and clock steps by comparing how far each moved. Video timecodes are parsed and printed here too. `Host` and `ClockKind` say what a session was recorded on.
This commit is contained in:
1 parent
ab0b943ba0
commit
d5eacecef8
17 files changed
+2676
-1
No files matched your search
Generated
+449
@@ -2,6 +2,21 @@
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "addr2line"
|
||||
version = "0.25.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
|
||||
dependencies = [
|
||||
"gimli",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "adler2"
|
||||
version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
|
||||
|
||||
[[package]]
|
||||
name = "anstream"
|
||||
version = "1.0.0"
|
||||
@@ -52,12 +67,33 @@ dependencies = [
|
||||
"windows-sys 0.60.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "backtrace"
|
||||
version = "0.3.76"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
|
||||
dependencies = [
|
||||
"addr2line",
|
||||
"cfg-if",
|
||||
"libc",
|
||||
"miniz_oxide",
|
||||
"object",
|
||||
"rustc-demangle",
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "2.11.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
|
||||
|
||||
[[package]]
|
||||
name = "cfg-if"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
|
||||
|
||||
[[package]]
|
||||
name = "clap"
|
||||
version = "4.6.1"
|
||||
@@ -99,12 +135,45 @@ version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
|
||||
|
||||
[[package]]
|
||||
name = "color-eyre"
|
||||
version = "0.6.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e5920befb47832a6d61ee3a3a846565cfa39b331331e68a3b1d1116630f2f26d"
|
||||
dependencies = [
|
||||
"backtrace",
|
||||
"color-spantrace",
|
||||
"eyre",
|
||||
"indenter",
|
||||
"once_cell",
|
||||
"owo-colors",
|
||||
"tracing-error",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "color-spantrace"
|
||||
version = "0.3.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b8b88ea9df13354b55bc7234ebcce36e6ef896aca2e42a15de9e10edce01b427"
|
||||
dependencies = [
|
||||
"once_cell",
|
||||
"owo-colors",
|
||||
"tracing-core",
|
||||
"tracing-error",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "colorchoice"
|
||||
version = "1.0.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
|
||||
|
||||
[[package]]
|
||||
name = "dyn-clone"
|
||||
version = "1.0.20"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
|
||||
|
||||
[[package]]
|
||||
name = "errno"
|
||||
version = "0.3.14"
|
||||
@@ -115,25 +184,65 @@ dependencies = [
|
||||
"windows-sys 0.52.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "eyre"
|
||||
version = "0.6.12"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7cd915d99f24784cdc19fd37ef22b97e3ff0ae756c7e492e9fbfe897d61e2aec"
|
||||
dependencies = [
|
||||
"indenter",
|
||||
"once_cell",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "gimli"
|
||||
version = "0.32.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
|
||||
|
||||
[[package]]
|
||||
name = "heck"
|
||||
version = "0.5.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
|
||||
|
||||
[[package]]
|
||||
name = "indenter"
|
||||
version = "0.3.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "964de6e86d545b246d84badc0fef527924ace5134f30641c203ef52ba83f58d5"
|
||||
|
||||
[[package]]
|
||||
name = "is_terminal_polyfill"
|
||||
version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
|
||||
|
||||
[[package]]
|
||||
name = "itoa"
|
||||
version = "1.0.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
||||
|
||||
[[package]]
|
||||
name = "komorebi-recorder"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"clap",
|
||||
"color-eyre",
|
||||
"libc",
|
||||
"schemars",
|
||||
"serde",
|
||||
"serde_json_lenient",
|
||||
"windows",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "lazy_static"
|
||||
version = "1.5.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
|
||||
|
||||
[[package]]
|
||||
name = "libc"
|
||||
version = "0.2.186"
|
||||
@@ -146,12 +255,54 @@ version = "0.12.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
|
||||
|
||||
[[package]]
|
||||
name = "memchr"
|
||||
version = "2.8.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
|
||||
|
||||
[[package]]
|
||||
name = "miniz_oxide"
|
||||
version = "0.8.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
|
||||
dependencies = [
|
||||
"adler2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "object"
|
||||
version = "0.37.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
|
||||
dependencies = [
|
||||
"memchr",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "once_cell"
|
||||
version = "1.21.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
|
||||
|
||||
[[package]]
|
||||
name = "once_cell_polyfill"
|
||||
version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "owo-colors"
|
||||
version = "4.3.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d211803b9b6b570f68772237e415a029d5a50c65d382910b879fb19d3271f94d"
|
||||
|
||||
[[package]]
|
||||
name = "pin-project-lite"
|
||||
version = "0.2.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
|
||||
|
||||
[[package]]
|
||||
name = "proc-macro2"
|
||||
version = "1.0.106"
|
||||
@@ -170,6 +321,32 @@ dependencies = [
|
||||
"proc-macro2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ref-cast"
|
||||
version = "1.0.25"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f354300ae66f76f1c85c5f84693f0ce81d747e2c3f21a45fef496d89c960bf7d"
|
||||
dependencies = [
|
||||
"ref-cast-impl",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ref-cast-impl"
|
||||
version = "1.0.25"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustc-demangle"
|
||||
version = "0.1.27"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d"
|
||||
|
||||
[[package]]
|
||||
name = "rustix"
|
||||
version = "1.1.4"
|
||||
@@ -183,6 +360,112 @@ dependencies = [
|
||||
"windows-sys 0.52.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ryu"
|
||||
version = "1.0.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
|
||||
|
||||
[[package]]
|
||||
name = "schemars"
|
||||
version = "1.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a2b42f36aa1cd011945615b92222f6bf73c599a102a300334cd7f8dbeec726cc"
|
||||
dependencies = [
|
||||
"dyn-clone",
|
||||
"ref-cast",
|
||||
"schemars_derive",
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "schemars_derive"
|
||||
version = "1.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7d115b50f4aaeea07e79c1912f645c7513d81715d0420f8bc77a18c6260b307f"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"serde_derive_internals",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde"
|
||||
version = "1.0.228"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
|
||||
dependencies = [
|
||||
"serde_core",
|
||||
"serde_derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_core"
|
||||
version = "1.0.228"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
|
||||
dependencies = [
|
||||
"serde_derive",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_derive"
|
||||
version = "1.0.228"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_derive_internals"
|
||||
version = "0.29.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_json"
|
||||
version = "1.0.149"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
|
||||
dependencies = [
|
||||
"itoa",
|
||||
"memchr",
|
||||
"serde",
|
||||
"serde_core",
|
||||
"zmij",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "serde_json_lenient"
|
||||
version = "0.2.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0e033097bf0d2b59a62b42c18ebbb797503839b26afdda2c4e1415cb6c813540"
|
||||
dependencies = [
|
||||
"itoa",
|
||||
"memchr",
|
||||
"ryu",
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "sharded-slab"
|
||||
version = "0.1.7"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
|
||||
dependencies = [
|
||||
"lazy_static",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "strsim"
|
||||
version = "0.11.1"
|
||||
@@ -210,6 +493,56 @@ dependencies = [
|
||||
"windows-sys 0.59.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "thread_local"
|
||||
version = "1.1.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tracing"
|
||||
version = "0.1.44"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
|
||||
dependencies = [
|
||||
"pin-project-lite",
|
||||
"tracing-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tracing-core"
|
||||
version = "0.1.36"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
|
||||
dependencies = [
|
||||
"once_cell",
|
||||
"valuable",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tracing-error"
|
||||
version = "0.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8b1581020d7a273442f5b45074a6a57d5757ad0a47dac0e9f0bd57b81936f3db"
|
||||
dependencies = [
|
||||
"tracing",
|
||||
"tracing-subscriber",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tracing-subscriber"
|
||||
version = "0.3.23"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
|
||||
dependencies = [
|
||||
"sharded-slab",
|
||||
"thread_local",
|
||||
"tracing-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "unicode-ident"
|
||||
version = "1.0.24"
|
||||
@@ -222,12 +555,113 @@ version = "0.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
|
||||
|
||||
[[package]]
|
||||
name = "valuable"
|
||||
version = "0.1.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
|
||||
|
||||
[[package]]
|
||||
name = "windows"
|
||||
version = "0.62.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
|
||||
dependencies = [
|
||||
"windows-collections",
|
||||
"windows-core",
|
||||
"windows-future",
|
||||
"windows-numerics",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-collections"
|
||||
version = "0.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
|
||||
dependencies = [
|
||||
"windows-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-core"
|
||||
version = "0.62.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
|
||||
dependencies = [
|
||||
"windows-implement",
|
||||
"windows-interface",
|
||||
"windows-link",
|
||||
"windows-result",
|
||||
"windows-strings",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-future"
|
||||
version = "0.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
|
||||
dependencies = [
|
||||
"windows-core",
|
||||
"windows-link",
|
||||
"windows-threading",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-implement"
|
||||
version = "0.60.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-interface"
|
||||
version = "0.59.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
"syn",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-link"
|
||||
version = "0.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
|
||||
|
||||
[[package]]
|
||||
name = "windows-numerics"
|
||||
version = "0.3.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
|
||||
dependencies = [
|
||||
"windows-core",
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-result"
|
||||
version = "0.4.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
|
||||
dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-strings"
|
||||
version = "0.5.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
|
||||
dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-sys"
|
||||
version = "0.52.0"
|
||||
@@ -288,6 +722,15 @@ dependencies = [
|
||||
"windows_x86_64_msvc 0.53.1",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-threading"
|
||||
version = "0.2.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
|
||||
dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows_aarch64_gnullvm"
|
||||
version = "0.52.6"
|
||||
@@ -383,3 +826,9 @@ name = "windows_x86_64_msvc"
|
||||
version = "0.53.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
|
||||
|
||||
[[package]]
|
||||
name = "zmij"
|
||||
version = "1.0.21"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
|
||||
@@ -41,6 +41,8 @@ Two things vary independently: the _host_ the recorder runs on (macOS or Windows
|
||||
records (komorebi for Mac or komorebi for Windows). A session records both, so one recorded on Windows can be
|
||||
investigated on a Mac. Every record in a session is stamped on one monotonic clock, and the files in it are never
|
||||
rewritten after they are written.
|
||||
[Architecture](docs/ARCHITECTURE.md) explains the model and which layer enforces each rule;
|
||||
[Platform](docs/PLATFORM.md) answers the same questions for each host.
|
||||
|
||||
## Crates
|
||||
|
||||
|
||||
+110
-1
@@ -1,36 +1,80 @@
|
||||
{
|
||||
"licenses": [
|
||||
[
|
||||
"0BSD",
|
||||
[
|
||||
"adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
],
|
||||
[
|
||||
"Apache-2.0",
|
||||
[
|
||||
"addr2line 0.25.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstream 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle 1.0.14 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle-parse 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle-query 1.1.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle-wincon 3.0.11 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"backtrace 0.3.76 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"cfg-if 1.0.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap 4.6.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap_builder 4.6.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap_derive 4.6.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap_lex 1.1.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"color-eyre 0.6.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"colorchoice 1.0.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"dyn-clone 1.0.20 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"indenter 0.3.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"is_terminal_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"lazy_static 1.5.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"object 0.37.3 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"ref-cast-impl 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"rustc-demangle 0.1.27 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_derive_internals 0.29.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"terminal_size 0.4.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-future 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-implement 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-interface 0.59.3 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-link 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-numerics 0.3.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-result 0.4.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-strings 0.5.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows_x86_64_msvc 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
@@ -41,6 +85,12 @@
|
||||
"rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
],
|
||||
[
|
||||
"BSL-1.0",
|
||||
[
|
||||
"ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
],
|
||||
[
|
||||
"LicenseRef-Komorebi-2.0",
|
||||
[
|
||||
@@ -50,37 +100,84 @@
|
||||
[
|
||||
"MIT",
|
||||
[
|
||||
"addr2line 0.25.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstream 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle 1.0.14 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle-parse 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle-query 1.1.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"anstyle-wincon 3.0.11 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"backtrace 0.3.76 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"cfg-if 1.0.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap 4.6.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap_builder 4.6.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap_derive 4.6.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"clap_lex 1.1.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"color-eyre 0.6.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"colorchoice 1.0.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"dyn-clone 1.0.20 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"indenter 0.3.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"is_terminal_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"lazy_static 1.5.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"object 0.37.3 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"owo-colors 4.3.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"ref-cast-impl 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"rustc-demangle 0.1.27 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"schemars 1.2.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"schemars_derive 1.2.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_derive_internals 0.29.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"sharded-slab 0.1.7 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"strsim 0.11.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"terminal_size 0.4.4 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"tracing 0.1.44 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"tracing-core 0.1.36 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"tracing-error 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"tracing-subscriber 0.3.23 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-future 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-implement 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-interface 0.59.3 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-link 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-numerics 0.3.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-result 0.4.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-strings 0.5.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows_x86_64_msvc 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index"
|
||||
"windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index",
|
||||
"zmij 1.0.21 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
],
|
||||
[
|
||||
@@ -88,6 +185,18 @@
|
||||
[
|
||||
"unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
],
|
||||
[
|
||||
"Unlicense",
|
||||
[
|
||||
"memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
],
|
||||
[
|
||||
"Zlib",
|
||||
[
|
||||
"miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index"
|
||||
]
|
||||
]
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
# Architecture
|
||||
|
||||
`komorebi-recorder` connects three things that do not know about each other: komorebi, which says what it is doing in
|
||||
a log and in events on a socket; the operating system, which says what it is doing in its own trace and shows it on a
|
||||
screen; and the person or agent who has to work out why they disagreed. It records all of them on one clock into a
|
||||
session directory, and reads that directory back.
|
||||
|
||||
Two things about it vary independently, and everything below is arranged so that neither leaks into the other.
|
||||
|
||||
| axis | what varies | where the variation lives | what a session records |
|
||||
|---|---|---|---|
|
||||
| host | the OS the recorder runs on: macOS or Windows (a third `unsupported` host builds anywhere) | [`platform`](../komorebi-recorder/src/platform/mod.rs), selected by `cfg` | `host` in the manifest |
|
||||
|
||||
## The master clock
|
||||
|
||||
Everything in a session is stamped on one clock: the host's monotonic clock, in nanoseconds. That is
|
||||
`mach_absolute_time` on macOS and `QueryPerformanceCounter` on Windows. Video frames and the OS trace are already on it.
|
||||
komorebi's log lines carry UTC wall-clock time, so they are mapped onto it: the recorder samples a paired reading of
|
||||
both clocks (an `Anchor`) at the start, every few seconds and at every sleep, and a `ClockMap` interpolates between
|
||||
them. A `JumpDetector` notices sleep and clock steps by comparing how far each clock moved between two observations,
|
||||
and the anchors on either side of the jump are what make the mapping right on both sides of it.
|
||||
|
||||
Three things are worth knowing before reading a session:
|
||||
|
||||
- The field names ending in `_mach_ns` keep their historical spelling. They hold master-clock nanoseconds on whichever
|
||||
host recorded the session; the manifest's `host.clock` says which clock that was (`mach`, `qpc` or `std`). A name that
|
||||
changed would stop older sessions being readable by newer builds and the reverse.
|
||||
- The master clock is not the wall clock. On macOS it pauses while the machine sleeps, so video time skips a sleep
|
||||
instead of showing a hole. Whether the performance counter counts a suspend on Windows is measured, not assumed.
|
||||
- A timestamp is a plain `u64` of nanoseconds. Nothing in the type system says which clock it is on: that is held by
|
||||
convention, and by the tests that place records at known times.
|
||||
|
||||
## The platform facade
|
||||
|
||||
The rest of the crate never names a system API. [`platform`](../komorebi-recorder/src/platform/mod.rs) is a facade of
|
||||
small modules (`clock`, `shell` and, as the recorder grows, `capture`, `power`, `session`, `trace`, `process`, `apps`
|
||||
and `window`), and `cfg` selects the directory behind it: `platform/macos/`, `platform/win/` or `platform/unsupported.rs`.
|
||||
Each host provides the same names with the same signatures. A missing or mismatched function is a compile error on the
|
||||
host being built, and on no other, so the Windows host is built from a Mac by `just check-windows` and by CI, and
|
||||
`unsupported` (which exists so that the commands that only read a session directory work on a Linux agent box) is built
|
||||
only on a third OS.
|
||||
|
||||
Where one host has no analogue of something, the facade function exists on both and one answers "nothing": `trace::start`
|
||||
on the `unsupported` host returns no taps and a line saying so, and `power::start` returns no watcher.
|
||||
|
||||
## Rules and the layer that enforces them
|
||||
|
||||
| Rule | Enforced by |
|
||||
|---|---|
|
||||
| Every host provides the same functions with the same signatures | the compiler, for the host being built; `just check-windows` and CI build the Windows host from a Mac; nothing builds `unsupported` |
|
||||
| A timestamp in a session is on the master clock | convention, and the tests that place records at known times: the type is a plain `u64` |
|
||||
@@ -0,0 +1,66 @@
|
||||
# Platform support
|
||||
|
||||
This document gathers, in one place, what differs by operating system. Most of the details are written down on the items
|
||||
that implement them; here the same questions are answered once per host, so that someone who has to run the recorder on
|
||||
a machine, or change it for one, does not have to read the code to find out.
|
||||
|
||||
The recorder is built for macOS and Windows. A third host, `unsupported`, builds on anything else so that the commands
|
||||
that only read a session directory work on a Linux agent box; recording there says that it cannot.
|
||||
|
||||
## Status
|
||||
|
||||
| host | built | run |
|
||||
|---|---|---|
|
||||
| macOS (Apple silicon) | yes | yes: written and run on macOS 26 |
|
||||
| Windows x86_64 | yes, natively on `windows-latest` and cross-compiled from a Mac | no: type-checked and cross-built only |
|
||||
| Windows ARM64 | yes, cross-built on an x86_64 runner | no |
|
||||
| anything else | the `unsupported` host builds | nothing records |
|
||||
|
||||
Nothing that touches a real Windows desktop has been seen running: the Windows host was written from the Windows API
|
||||
documentation and komorebi for Windows' source, and every claim below about Windows says what the code does, not what
|
||||
was observed.
|
||||
|
||||
## Vocabulary
|
||||
|
||||
- **Host**: the OS the recorder runs on. It decides how the screen is captured, which clock is read, how the OS says it
|
||||
is going to sleep and what the OS trace is made of.
|
||||
- **Flavor**: which komorebi is being recorded. There is one per OS, and a recorder watches the one on its own host, but
|
||||
a session records its flavor, so a session from either can be read on either host.
|
||||
- **Master clock**: the host's monotonic clock, in nanoseconds, on which every record in a session is stamped.
|
||||
- **Session**: the directory a recording is written to.
|
||||
- **Segment**: one contiguous stretch of one display's video, a file of its own. A display that is unplugged and plugged
|
||||
in again has two.
|
||||
|
||||
## The same questions, per host
|
||||
|
||||
### The master clock
|
||||
|
||||
| | macOS | Windows | unsupported |
|
||||
|---|---|---|---|
|
||||
| clock | `mach_absolute_time`, scaled by `mach_timebase_info` | `QueryPerformanceCounter`, scaled by `QueryPerformanceFrequency` (10 MHz when Windows will not say) | the time since the first reading in the process, plus one second so that no reading is zero |
|
||||
| `host.clock` in the manifest | `mach` | `qpc` | `std` |
|
||||
| counts the time the machine sleeps | no | not known: measured, not assumed | no |
|
||||
| other clocks read beside it | `mach_continuous_time`, which counts sleep | `QueryInterruptTime`, which counts sleep, and `QueryUnbiasedInterruptTimePrecise`, which does not | none |
|
||||
|
||||
Video frame times and the OS trace are on the master clock already on both hosts (ScreenCaptureKit and the unified log's
|
||||
`machTimestamp` on a Mac; Windows.Graphics.Capture on Windows). The field names ending in `_mach_ns` are spelled that way
|
||||
on every host: see [the architecture](ARCHITECTURE.md#the-master-clock).
|
||||
|
||||
## Degraded modes
|
||||
|
||||
- `record --no-video` records everything but the screen, on the same clock. It asks the system nothing about displays and
|
||||
needs no permission.
|
||||
- `record --no-komorebi` skips touching komorebi altogether, and `--no-oslog` skips the OS trace.
|
||||
- A komorebi that is not running when a recording starts is not an error: it is noted, and the recorder subscribes when
|
||||
it appears.
|
||||
- The `unsupported` host investigates sessions and refuses to record.
|
||||
|
||||
## Advice by audience
|
||||
|
||||
- **Recording on macOS.** Grant Screen Recording to the terminal, and start komorebi with `--log-level trace`.
|
||||
- **Recording on Windows.** There is nothing to grant. Use `komorebi-recorder.exe` for commands, since the GUI build
|
||||
prints nowhere, and start komorebi with `--log-level debug` and `RUST_LOG=komorebi=debug`.
|
||||
- **Investigating on any host.** A session is read the same everywhere. `ffmpeg` is needed only for `frames` and
|
||||
`selftest`.
|
||||
- **Changing code that has a host-specific part.** Provide the function on every host, and run `just check-windows` from a
|
||||
Mac: it type-checks every `cfg(windows)` line, tests included.
|
||||
@@ -7,3 +7,50 @@ repository.workspace = true
|
||||
|
||||
[dependencies]
|
||||
clap = { workspace = true }
|
||||
color-eyre = { workspace = true }
|
||||
schemars = { workspace = true }
|
||||
serde = { workspace = true }
|
||||
serde_json = { workspace = true }
|
||||
|
||||
[target.'cfg(target_os = "macos")'.dependencies]
|
||||
libc = "0.2"
|
||||
|
||||
[target.'cfg(windows)'.dependencies]
|
||||
windows = { version = "0.62", features = [
|
||||
"Foundation",
|
||||
"Graphics",
|
||||
"Graphics_Capture",
|
||||
"Graphics_DirectX",
|
||||
"Graphics_DirectX_Direct3D11",
|
||||
"Wdk_System_SystemServices",
|
||||
"Win32_Foundation",
|
||||
"Win32_Graphics_Direct3D",
|
||||
"Win32_Graphics_Direct3D11",
|
||||
"Win32_Graphics_Dwm",
|
||||
"Win32_Graphics_Dxgi",
|
||||
"Win32_Graphics_Dxgi_Common",
|
||||
"Win32_Graphics_Gdi",
|
||||
"Win32_Media",
|
||||
"Win32_Media_MediaFoundation",
|
||||
"Win32_System_Com",
|
||||
"Win32_System_Com_StructuredStorage",
|
||||
"Win32_System_EventLog",
|
||||
"Win32_System_LibraryLoader",
|
||||
"Win32_System_Performance",
|
||||
"Win32_System_Power",
|
||||
"Win32_System_RemoteDesktop",
|
||||
"Win32_System_StationsAndDesktops",
|
||||
"Win32_System_SystemInformation",
|
||||
"Win32_System_SystemServices",
|
||||
"Win32_System_Threading",
|
||||
"Win32_System_Variant",
|
||||
"Win32_System_WinRT",
|
||||
"Win32_System_WinRT_Direct3D11",
|
||||
"Win32_System_WinRT_Graphics_Capture",
|
||||
"Win32_System_WindowsProgramming",
|
||||
"Win32_UI_Accessibility",
|
||||
"Win32_UI_HiDpi",
|
||||
"Win32_UI_Shell",
|
||||
"Win32_UI_Shell_Common",
|
||||
"Win32_UI_WindowsAndMessaging",
|
||||
] }
|
||||
@@ -0,0 +1,949 @@
|
||||
//! The master clock: the one monotonic clock every record in a session is stamped on, and the
|
||||
//! conversions between it, the wall clock and video time.
|
||||
//!
|
||||
//! Every source in a recording is expressed in nanoseconds on one host monotonic clock: capture
|
||||
//! frame timestamps, the OS trace, komorebi's subscriber events, incidents. komorebi's own log
|
||||
//! lines are the exception. They carry a UTC wall clock time, and are mapped
|
||||
//! onto the master clock with the [`Anchor`]s sampled while recording.
|
||||
//!
|
||||
//! # Which clock is the master clock
|
||||
//!
|
||||
//! [`mono_now_ns`] reads it, through [`crate::platform::clock`], and [`Host::clock`] names it: the
|
||||
//! field holds the [`ClockKind`] the session was recorded with, which the manifest stores as
|
||||
//! `host.clock`. It does not name the wall clock, or any [`ReferenceClock`].
|
||||
//!
|
||||
//! | [`ClockKind`] | `host.clock` | read with |
|
||||
//! |---|---|---|
|
||||
//! | [`Mach`](crate::platform::ClockKind::Mach) | `mach` | `mach_absolute_time`, on macOS |
|
||||
//! | [`Qpc`](crate::platform::ClockKind::Qpc) | `qpc` | `QueryPerformanceCounter`, on Windows |
|
||||
//! | [`Std`](crate::platform::ClockKind::Std) | `std` | [`std::time::Instant`] since the first reading in the process, plus one second so that it is never zero, on a host with no capture |
|
||||
//!
|
||||
//! `mach_absolute_time` pauses while the machine sleeps. Whether the Windows counter does is not
|
||||
//! assumed: `doctor --probe clock` measures it, and where the OS can announce a sleep the
|
||||
//! recorder listens for it (`platform::power`) rather than inferring it from the clocks alone.
|
||||
//!
|
||||
//! The `*_mach_ns` field names throughout a session are historical: they mean "master monotonic
|
||||
//! nanoseconds", whichever clock that was, and keeping them means a session written by any build
|
||||
//! is readable by any other. `host.clock` is what says which clock the numbers are on.
|
||||
//!
|
||||
//! # The four scales
|
||||
//!
|
||||
//! | Scale | Unit | Where it appears | Converted with |
|
||||
//! |---|---|---|---|
|
||||
//! | host ticks | ticks of the OS counter | raw counter reads, the unified log's `machTimestamp` | [`Timebase`] |
|
||||
//! | master clock | nanoseconds, `u64` | every `*_mach_ns` field | (the scale the others convert to and from) |
|
||||
//! | wall time | microseconds since the Unix epoch, `i64`, UTC | komorebi's log lines, every `wall_us` field | [`ClockMap`] |
|
||||
//! | video time | seconds, `f64`, since the first captured frame | timecodes (see [`crate::timecode`]), `video_s` fields | subtracting the master clock time of video `t = 0` |
|
||||
//!
|
||||
//! Video `t = 0` is the master clock time of the earliest first frame across displays, recorded in
|
||||
//! the manifest as `video_t0_mach_ns`; with no frame at all it is the recording's start. A time
|
||||
//! before the first frame is negative. The session manifest's `video_seconds` and
|
||||
//! `mach_at_video_seconds` do that subtraction in each direction.
|
||||
//!
|
||||
//! # How the pieces relate
|
||||
//!
|
||||
//! * [`Timebase`] says what one host tick is worth. It is read from the OS once ([`timebase`]),
|
||||
//! and stored in the manifest, so that a session recorded on one machine is read on another with
|
||||
//! the tick size of the machine that recorded it.
|
||||
//! * [`Anchor`] pairs one wall clock reading with the master clock time at which it was made.
|
||||
//! The recording loop samples one about every 5 seconds, and one on either side of every sleep.
|
||||
//! * [`ClockMap`] is built from a session's anchors, and maps between wall time and the master
|
||||
//! clock by interpolating between them.
|
||||
//! * [`JumpDetector`] compares the wall clock with the master clock over each loop iteration, and
|
||||
//! reports a [`Jump`] when they disagree. The two anchors of a [`Jump`] are the pair of anchors
|
||||
//! [`ClockMap`] needs to treat a sleep as a step, rather than as drift.
|
||||
//! * [`ReferenceClock`] is another host clock, read next to the master clock so that a probe can
|
||||
//! say what the master clock does across a sleep.
|
||||
//!
|
||||
//! # Example: ticks, master clock, wall time and video time
|
||||
//!
|
||||
//! ```rust
|
||||
//! use komorebi_recorder::clock::{Anchor, ClockMap, Timebase};
|
||||
//!
|
||||
//! // a counter that ticks at 24 MHz, which is 125/3 nanoseconds a tick
|
||||
//! let timebase = Timebase::from_frequency(24_000_000);
|
||||
//! assert_eq!(timebase, Timebase { numer: 125, denom: 3 });
|
||||
//!
|
||||
//! // host ticks -> master clock nanoseconds
|
||||
//! let mach_ns = timebase.ticks_to_ns(2_400_000_000);
|
||||
//! assert_eq!(mach_ns, 100_000_000_000);
|
||||
//!
|
||||
//! // two anchors taken 5 seconds apart, as the recorder does
|
||||
//! let map = ClockMap::new(vec![
|
||||
//! Anchor { wall_us: 1_800_000_000_000_000, mach_ns: 100_000_000_000 },
|
||||
//! Anchor { wall_us: 1_800_000_005_000_000, mach_ns: 105_000_000_000 },
|
||||
//! ]);
|
||||
//!
|
||||
//! // master clock -> wall time, and back
|
||||
//! let wall_us = map.mach_to_wall(102_500_000_000).expect("the map has anchors");
|
||||
//! assert_eq!(wall_us, 1_800_000_002_500_000);
|
||||
//! assert_eq!(map.wall_to_mach(wall_us), Some(102_500_000_000));
|
||||
//!
|
||||
//! // master clock -> video time, for a first frame that was captured at 101 s on the master clock
|
||||
//! let video_t0_mach_ns = 101_000_000_000_i128;
|
||||
//! let video_s = (102_500_000_000_i128 - video_t0_mach_ns) as f64 / 1e9;
|
||||
//! assert_eq!(video_s, 1.5);
|
||||
//!
|
||||
//! // and back, from video time to the master clock
|
||||
//! assert_eq!(video_t0_mach_ns + (video_s * 1e9).round() as i128, 102_500_000_000);
|
||||
//!
|
||||
//! // a time before the first frame is negative in video time
|
||||
//! assert_eq!((100_500_000_000_i128 - video_t0_mach_ns) as f64 / 1e9, -0.5);
|
||||
//! ```
|
||||
//!
|
||||
//! [`Host::clock`]: crate::platform::Host::clock
|
||||
//! [`ClockKind`]: crate::platform::ClockKind
|
||||
|
||||
use crate::platform;
|
||||
use serde::Deserialize;
|
||||
use serde::Serialize;
|
||||
use std::time::SystemTime;
|
||||
use std::time::UNIX_EPOCH;
|
||||
|
||||
/// The size of one tick of the host clock: `numer / denom` nanoseconds.
|
||||
///
|
||||
/// It is read from the OS once ([`timebase`]) and stored in a session's manifest as `timebase`, so
|
||||
/// that a session recorded on one machine is converted with the tick size of the machine that
|
||||
/// recorded it, and not with the reader's. The unified log's `machTimestamp` is in ticks of this
|
||||
/// size, and the manifest's timebase is what converts it.
|
||||
///
|
||||
/// A timebase this crate produces has a non-zero `numer` and `denom`. The fields are public and
|
||||
/// are read back from `session.json`, so a hand-edited manifest can hold zeros, which make
|
||||
/// [`ticks_to_ns`](Timebase::ticks_to_ns) and [`ns_to_ticks`](Timebase::ns_to_ticks) panic.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::Timebase;
|
||||
///
|
||||
/// // Apple silicon's counter: 24 MHz, so 125/3 nanoseconds a tick
|
||||
/// let timebase = Timebase { numer: 125, denom: 3 };
|
||||
/// assert_eq!(timebase.ticks_to_ns(24_000_000), 1_000_000_000);
|
||||
/// assert_eq!(timebase.ns_to_ticks(1_000_000_000), 24_000_000);
|
||||
/// ```
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||||
pub struct Timebase {
|
||||
/// The numerator of the nanoseconds a tick is worth.
|
||||
pub numer: u32,
|
||||
/// The denominator of the nanoseconds a tick is worth.
|
||||
pub denom: u32,
|
||||
}
|
||||
|
||||
impl Timebase {
|
||||
/// Returns the timebase of a counter that ticks `hertz` times a second, as
|
||||
/// `QueryPerformanceCounter` does.
|
||||
///
|
||||
/// One tick is `1e9 / hertz` nanoseconds. The fraction is reduced, so a 10 MHz counter is
|
||||
/// `100/1`, not `1000000000/10000000`. A counter faster than about 4.29 GHz has a reduced
|
||||
/// denominator that does not fit in a `u32`: both parts are then halved until they do, which
|
||||
/// keeps the ratio approximately. A `hertz` of zero is treated as one.
|
||||
///
|
||||
/// The result always has a non-zero `numer` and `denom`.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::Timebase;
|
||||
///
|
||||
/// // the usual `QueryPerformanceFrequency`: 10 MHz, which is 100 ns a tick
|
||||
/// assert_eq!(Timebase::from_frequency(10_000_000), Timebase { numer: 100, denom: 1 });
|
||||
///
|
||||
/// // Apple silicon's counter
|
||||
/// assert_eq!(Timebase::from_frequency(24_000_000), Timebase { numer: 125, denom: 3 });
|
||||
///
|
||||
/// // a nanosecond counter, and a nonsense zero, are both fine
|
||||
/// assert_eq!(Timebase::from_frequency(1_000_000_000), Timebase { numer: 1, denom: 1 });
|
||||
/// assert_eq!(Timebase::from_frequency(0).ticks_to_ns(5), 5_000_000_000);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn from_frequency(hertz: u64) -> Self {
|
||||
fn gcd(a: u64, b: u64) -> u64 {
|
||||
if b == 0 { a } else { gcd(b, a % b) }
|
||||
}
|
||||
|
||||
let hertz = hertz.max(1);
|
||||
let divisor = gcd(1_000_000_000, hertz);
|
||||
let (mut numer, mut denom) = (1_000_000_000 / divisor, hertz / divisor);
|
||||
while numer > u64::from(u32::MAX) || denom > u64::from(u32::MAX) {
|
||||
numer = (numer / 2).max(1);
|
||||
denom = (denom / 2).max(1);
|
||||
}
|
||||
|
||||
Self {
|
||||
numer: numer as u32,
|
||||
denom: denom as u32,
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns `ticks` host clock ticks as nanoseconds: `ticks * numer / denom`.
|
||||
///
|
||||
/// The product is computed in 128 bits, so it cannot overflow, and the quotient is truncated
|
||||
/// toward zero. A result that does not fit in a `u64` is truncated to its low 64 bits.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// Panics if `denom` is zero.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::Timebase;
|
||||
///
|
||||
/// let timebase = Timebase { numer: 125, denom: 3 };
|
||||
/// assert_eq!(timebase.ticks_to_ns(24_000_000), 1_000_000_000);
|
||||
///
|
||||
/// // one tick is 41.67 ns, truncated
|
||||
/// assert_eq!(timebase.ticks_to_ns(1), 41);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn ticks_to_ns(self, ticks: u64) -> u64 {
|
||||
(u128::from(ticks) * u128::from(self.numer) / u128::from(self.denom)) as u64
|
||||
}
|
||||
|
||||
/// Returns `ns` nanoseconds as host clock ticks: `ns * denom / numer`.
|
||||
///
|
||||
/// The product is computed in 128 bits, so it cannot overflow, and the quotient is truncated
|
||||
/// toward zero. A result that does not fit in a `u64` is truncated to its low 64 bits.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// Panics if `numer` is zero.
|
||||
///
|
||||
/// # Example: a round trip can lose a tick
|
||||
///
|
||||
/// Both directions truncate, so a tick count that goes to nanoseconds and back comes back
|
||||
/// equal only when the nanoseconds were exact:
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::Timebase;
|
||||
///
|
||||
/// let timebase = Timebase { numer: 125, denom: 3 };
|
||||
/// assert_eq!(timebase.ns_to_ticks(timebase.ticks_to_ns(24_000_000)), 24_000_000);
|
||||
/// assert_eq!(timebase.ns_to_ticks(timebase.ticks_to_ns(1)), 0);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn ns_to_ticks(self, ns: u64) -> u64 {
|
||||
(u128::from(ns) * u128::from(self.denom) / u128::from(self.numer)) as u64
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns what one tick of the host clock is worth in nanoseconds.
|
||||
///
|
||||
/// It is the host's own: from `mach_timebase_info` on macOS (125/3 on Apple silicon, and 1/1 if the
|
||||
/// OS reports an unusable one), from [`Timebase::from_frequency`] of `QueryPerformanceFrequency` on
|
||||
/// Windows (10 MHz if that cannot be read), and 1/1 on a host with no capture, whose clock already
|
||||
/// counts nanoseconds. A session records the timebase it was written with in its manifest; use that
|
||||
/// one, not this, to convert a recorded session's ticks.
|
||||
#[must_use]
|
||||
pub fn timebase() -> Timebase {
|
||||
platform::clock::timebase()
|
||||
}
|
||||
|
||||
/// Another clock the host has, read alongside the master clock to find out what the master clock
|
||||
/// does while the machine sleeps.
|
||||
///
|
||||
/// A reference clock is never used to stamp a record. `doctor` reads each one together with the
|
||||
/// master clock and the wall clock, and reports how far each moved across a sleep.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, schemars::JsonSchema)]
|
||||
pub struct ReferenceClock {
|
||||
/// The name of the OS clock, as the OS spells it (`mach_continuous_time`).
|
||||
pub name: String,
|
||||
/// Whether it keeps counting while the machine is suspended.
|
||||
pub counts_sleep: bool,
|
||||
/// Its reading, in nanoseconds from an origin that the clock chooses: only differences between
|
||||
/// two readings of the same clock mean anything.
|
||||
pub ns: u64,
|
||||
}
|
||||
|
||||
/// Returns a reading of each of the host's other clocks (see [`ReferenceClock`]).
|
||||
///
|
||||
/// On macOS that is `mach_continuous_time`, which counts the time the machine sleeps. On Windows
|
||||
/// it is `QueryInterruptTime`, which counts it, and `QueryUnbiasedInterruptTimePrecise`, which
|
||||
/// does not. A host with no capture has none.
|
||||
#[must_use]
|
||||
pub fn reference_clocks() -> Vec<ReferenceClock> {
|
||||
platform::clock::reference_clocks()
|
||||
}
|
||||
|
||||
/// Returns the master clock in nanoseconds: the host monotonic clock every record in a session is
|
||||
/// on.
|
||||
///
|
||||
/// On macOS this is `mach_absolute_time`, which pauses while the machine sleeps; on Windows it is
|
||||
/// `QueryPerformanceCounter`. The `*_mach_ns` fields in a session keep their historical names and
|
||||
/// hold this value; the manifest's `host.clock` says which clock it was.
|
||||
///
|
||||
/// The origin is chosen by the OS, so a reading means something only next to another reading of the
|
||||
/// same clock. The clock is monotonic: it does not go backwards, and `doctor` reports whether it
|
||||
/// did while it was read.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::mono_now_ns;
|
||||
///
|
||||
/// let first = mono_now_ns();
|
||||
/// let second = mono_now_ns();
|
||||
/// assert!(second >= first);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn mono_now_ns() -> u64 {
|
||||
platform::clock::now_ns()
|
||||
}
|
||||
|
||||
/// Returns the wall clock in microseconds since the Unix epoch (UTC).
|
||||
///
|
||||
/// Unlike [`mono_now_ns`], the wall clock can be stepped, forwards or backwards, by the user or by
|
||||
/// time synchronization, and keeps counting while the machine sleeps. A time before 1970, which
|
||||
/// means the clock is badly wrong, is returned as a negative number rather than as an error.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::wall_now_us;
|
||||
///
|
||||
/// // after 2020-01-01 and before 2100-01-01
|
||||
/// let now = wall_now_us();
|
||||
/// assert!(now > 1_577_836_800_000_000);
|
||||
/// assert!(now < 4_102_444_800_000_000);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn wall_now_us() -> i64 {
|
||||
match SystemTime::now().duration_since(UNIX_EPOCH) {
|
||||
Ok(since) => since.as_micros() as i64,
|
||||
// before 1970: the clock is badly wrong, but a negative time is still a time
|
||||
Err(before) => -(before.duration().as_micros() as i64),
|
||||
}
|
||||
}
|
||||
|
||||
/// A paired reading of the wall clock and the master clock: the master clock time at which the
|
||||
/// wall clock read `wall_us`.
|
||||
///
|
||||
/// An anchor is the only link between komorebi's log, which is stamped with the wall clock, and
|
||||
/// everything else, which is on the master clock. A session keeps a series of them in its manifest
|
||||
/// (`anchors`), and [`ClockMap`] interpolates between them.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::{wall_now_us, Anchor};
|
||||
///
|
||||
/// let anchor = Anchor::sample();
|
||||
/// // the wall clock was read a moment ago
|
||||
/// assert!((wall_now_us() - anchor.wall_us).abs() < 1_000_000);
|
||||
/// ```
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||||
pub struct Anchor {
|
||||
/// The wall clock, in microseconds since the Unix epoch (UTC).
|
||||
pub wall_us: i64,
|
||||
/// The master clock, in nanoseconds, at the same moment.
|
||||
pub mach_ns: u64,
|
||||
}
|
||||
|
||||
impl Anchor {
|
||||
/// Takes a tight paired reading: several back-to-back samples, keeping the one whose wall read
|
||||
/// was bracketed by the narrowest pair of mach reads, which bounds the pairing error to the
|
||||
/// duration of a couple of syscalls.
|
||||
///
|
||||
/// Seven samples are taken. The `mach_ns` of the one kept is the midpoint of the two master
|
||||
/// clock reads around its wall clock read.
|
||||
#[must_use]
|
||||
pub fn sample() -> Self {
|
||||
let mut best: Option<(u64, Anchor)> = None;
|
||||
for _ in 0..7 {
|
||||
let before = mono_now_ns();
|
||||
let wall_us = wall_now_us();
|
||||
let after = mono_now_ns();
|
||||
let width = after.saturating_sub(before);
|
||||
let anchor = Anchor {
|
||||
wall_us,
|
||||
mach_ns: before + width / 2,
|
||||
};
|
||||
|
||||
if best.is_none_or(|(best_width, _)| width < best_width) {
|
||||
best = Some((width, anchor));
|
||||
}
|
||||
}
|
||||
|
||||
best.map(|(_, anchor)| anchor).unwrap_or_else(|| Anchor {
|
||||
wall_us: wall_now_us(),
|
||||
mach_ns: mono_now_ns(),
|
||||
})
|
||||
}
|
||||
|
||||
/// The wall clock minus the mach clock, in microseconds.
|
||||
fn offset_us(self) -> i128 {
|
||||
i128::from(self.wall_us) - i128::from(self.mach_ns / 1_000)
|
||||
}
|
||||
}
|
||||
|
||||
/// How far the wall clock must outrun the mach clock between two close observations for it to
|
||||
/// count as a jump. Observations are made every ~50 ms, so ordinary drift is microseconds.
|
||||
const JUMP_THRESHOLD_NS: i128 = 1_000_000_000;
|
||||
|
||||
/// A discontinuity between the wall clock and the master clock, as [`JumpDetector::observe`]
|
||||
/// reports it.
|
||||
#[derive(Debug, Clone, Copy, PartialEq)]
|
||||
pub struct Jump {
|
||||
/// How far the wall clock moved beyond the master clock, in seconds. Positive: the machine
|
||||
/// slept (mach time pauses while asleep, wall time does not) or the clock stepped forward.
|
||||
/// Negative: the wall clock was stepped back.
|
||||
pub seconds: f64,
|
||||
/// The last good pairing before the jump: the previous observation.
|
||||
pub before: Anchor,
|
||||
/// The first pairing after the jump: the observation that found it.
|
||||
pub after: Anchor,
|
||||
}
|
||||
|
||||
/// Notices sleep/wake and clock steps by watching both clocks.
|
||||
///
|
||||
/// Feed it a fresh [`Anchor`] every loop iteration. When the two clocks disagree about how much
|
||||
/// time passed since the previous observation, the machine was suspended (or the clock was
|
||||
/// stepped), and the two anchors on either side of the discontinuity are exactly what
|
||||
/// [`ClockMap`] needs to map wall time to mach time correctly on both sides of it.
|
||||
///
|
||||
/// The detector is a state machine with one piece of state, the previous observation. It reports a
|
||||
/// [`Jump`] when the wall clock and the master clock moved by amounts that differ by 1 second or
|
||||
/// more since then. Observations are expected about every 50 ms, so ordinary drift is
|
||||
/// microseconds, and a process that was merely descheduled for a long time is not a jump, because
|
||||
/// both clocks moved together. A suspension shorter than 1 second is not reported.
|
||||
///
|
||||
/// On a host whose master clock keeps counting through a sleep, the two clocks do not disagree and
|
||||
/// a sleep is not noticed this way: see the module docs, and `PowerTracker` for the OS's own
|
||||
/// announcement of a sleep.
|
||||
///
|
||||
/// # Example: noticing a sleep, and mapping time across it
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::{Anchor, ClockMap, JumpDetector};
|
||||
///
|
||||
/// // wall time 2000 s and master clock time 1000 s are the same moment
|
||||
/// let start = Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 };
|
||||
/// let mut detector = JumpDetector::new(start);
|
||||
///
|
||||
/// // 50 ms later on both clocks: nothing to report
|
||||
/// let before = Anchor { wall_us: 2_000_050_000, mach_ns: 1_000_050_000_000 };
|
||||
/// assert_eq!(detector.observe(before), None);
|
||||
///
|
||||
/// // the lid is closed for an hour: the wall clock moves on, the master clock barely does
|
||||
/// let after = Anchor {
|
||||
/// wall_us: 2_000_100_000 + 3_600_000_000,
|
||||
/// mach_ns: 1_000_100_000_000,
|
||||
/// };
|
||||
/// let jump = detector.observe(after).expect("the clocks disagree by an hour");
|
||||
/// assert!((jump.seconds - 3_600.0).abs() < 0.01);
|
||||
/// assert_eq!((jump.before, jump.after), (before, after));
|
||||
///
|
||||
/// // with both anchors in the map, wall time maps correctly on either side of the sleep
|
||||
/// let map = ClockMap::new(vec![jump.before, jump.after]);
|
||||
/// assert_eq!(map.wall_to_mach(2_000_050_000), Some(1_000_050_000_000));
|
||||
/// let two_seconds_after_waking = after.wall_us + 2_000_000;
|
||||
/// assert_eq!(map.wall_to_mach(two_seconds_after_waking), Some(1_002_100_000_000));
|
||||
///
|
||||
/// // the detector carries on from the new position
|
||||
/// let later = Anchor { wall_us: after.wall_us + 50_000, mach_ns: after.mach_ns + 50_000_000 };
|
||||
/// assert_eq!(detector.observe(later), None);
|
||||
/// ```
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
pub struct JumpDetector {
|
||||
last: Anchor,
|
||||
}
|
||||
|
||||
impl JumpDetector {
|
||||
/// Returns a detector whose previous observation is `first`.
|
||||
#[must_use]
|
||||
pub fn new(first: Anchor) -> Self {
|
||||
Self { last: first }
|
||||
}
|
||||
|
||||
/// Compares `now` with the previous observation, and makes `now` the previous observation.
|
||||
///
|
||||
/// Returns a [`Jump`] if the wall clock and the master clock moved by amounts that differ by
|
||||
/// at least 1 second, in either direction, and `None` otherwise. The observation is recorded
|
||||
/// either way, so one discontinuity is reported once.
|
||||
pub fn observe(&mut self, now: Anchor) -> Option<Jump> {
|
||||
let wall_ns = (i128::from(now.wall_us) - i128::from(self.last.wall_us)) * 1_000;
|
||||
let mach_ns = i128::from(now.mach_ns) - i128::from(self.last.mach_ns);
|
||||
let difference = wall_ns - mach_ns;
|
||||
let before = std::mem::replace(&mut self.last, now);
|
||||
|
||||
(difference.abs() >= JUMP_THRESHOLD_NS).then_some(Jump {
|
||||
seconds: difference as f64 / 1e9,
|
||||
before,
|
||||
after: now,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Segments whose wall and mach durations disagree by more than this are treated as a clock step
|
||||
/// (an NTP jump, or the machine sleeping while the mach clock was paused) rather than as drift.
|
||||
const STEP_THRESHOLD_NS: i128 = 20_000_000;
|
||||
|
||||
/// A two-way map between wall clock time and the master clock, built by piecewise-linear
|
||||
/// interpolation between the anchors sampled during a recording.
|
||||
///
|
||||
/// A map is built from a session's anchors (the manifest's `anchors`) and answers in both
|
||||
/// directions: [`wall_to_mach`] turns a wall clock time, such as one of komorebi's log lines, into
|
||||
/// the master clock, and [`mach_to_wall`] does the reverse, to show a master clock time as UTC.
|
||||
///
|
||||
/// Each pair of neighboring anchors, ordered by master clock time, is a segment. The wall clock
|
||||
/// and the master clock tick at slightly different rates, so inside a segment a time is
|
||||
/// interpolated linearly. If the two clocks moved by amounts that differ by more than 20 ms over a
|
||||
/// segment, the segment holds a step rather than drift: the machine slept while the master clock
|
||||
/// was paused, or the wall clock was stepped. Where in the segment the step happened is not
|
||||
/// known, so a time inside it is taken from the nearer of the segment's two anchors, using that
|
||||
/// anchor's offset between the clocks. Outside the first and last anchors, a time is taken
|
||||
/// from the nearer end in the same way. With a single anchor, the map is a constant offset.
|
||||
///
|
||||
/// Both directions return `None` if, and only if, the map has no anchors.
|
||||
///
|
||||
/// A sleep inside a segment is placed at the nearer anchor, which is why the recorder adds an
|
||||
/// anchor on either side of every sleep it finds (see [`JumpDetector`]).
|
||||
///
|
||||
/// The anchors of a map are guaranteed to be sorted by master clock time, with no two at the same
|
||||
/// time, because [`ClockMap::new`] is the only way to make one that has any: the field is private.
|
||||
///
|
||||
/// ```rust,compile_fail,E0451
|
||||
/// use komorebi_recorder::clock::{Anchor, ClockMap};
|
||||
///
|
||||
/// // an unsorted list of anchors, which `ClockMap::new` would put in order
|
||||
/// let anchors = vec![
|
||||
/// Anchor { wall_us: 2_005_000_000, mach_ns: 1_005_000_000_000 },
|
||||
/// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 },
|
||||
/// ];
|
||||
/// let _map = ClockMap { anchors };
|
||||
/// ```
|
||||
///
|
||||
/// # Example: a clock step
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::{Anchor, ClockMap};
|
||||
///
|
||||
/// let at = |wall_s: i64, mach_s: u64| Anchor {
|
||||
/// wall_us: wall_s * 1_000_000,
|
||||
/// mach_ns: mach_s * 1_000_000_000,
|
||||
/// };
|
||||
///
|
||||
/// // the wall clock jumps forward 30 s between the second and third anchors, while the master
|
||||
/// // clock moves 5 s: the machine slept, or the clock was stepped
|
||||
/// let map = ClockMap::new(vec![at(2000, 1000), at(2005, 1005), at(2040, 1010)]);
|
||||
///
|
||||
/// // before the step, the clocks are 1000 s apart
|
||||
/// assert_eq!(map.wall_to_mach(2_001_000_000), Some(1_001_000_000_000));
|
||||
/// // after it, 1030 s apart
|
||||
/// assert_eq!(map.wall_to_mach(2_039_000_000), Some(1_009_000_000_000));
|
||||
/// // and the other direction agrees on both sides
|
||||
/// assert_eq!(map.mach_to_wall(1_001_000_000_000), Some(2_001_000_000));
|
||||
/// assert_eq!(map.mach_to_wall(1_009_000_000_000), Some(2_039_000_000));
|
||||
///
|
||||
/// // an empty map has no answer
|
||||
/// assert_eq!(ClockMap::default().wall_to_mach(1), None);
|
||||
/// ```
|
||||
///
|
||||
/// [`wall_to_mach`]: ClockMap::wall_to_mach
|
||||
/// [`mach_to_wall`]: ClockMap::mach_to_wall
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct ClockMap {
|
||||
anchors: Vec<Anchor>,
|
||||
}
|
||||
|
||||
impl ClockMap {
|
||||
/// Returns a map over `anchors`, which may be given in any order.
|
||||
///
|
||||
/// The anchors are sorted by master clock time, and of several with the same master clock time
|
||||
/// only the first given is kept.
|
||||
#[must_use]
|
||||
pub fn new(mut anchors: Vec<Anchor>) -> Self {
|
||||
anchors.sort_by_key(|anchor| anchor.mach_ns);
|
||||
anchors.dedup_by_key(|anchor| anchor.mach_ns);
|
||||
Self { anchors }
|
||||
}
|
||||
|
||||
/// Returns the anchors the map was built from, ascending by master clock time, with no two
|
||||
/// sharing a master clock time.
|
||||
#[must_use]
|
||||
pub fn anchors(&self) -> &[Anchor] {
|
||||
&self.anchors
|
||||
}
|
||||
|
||||
/// Returns true if and only if the map has no anchors, in which case every lookup returns
|
||||
/// `None`.
|
||||
#[must_use]
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.anchors.is_empty()
|
||||
}
|
||||
|
||||
/// Whether the segment between two anchors contains a clock step rather than plain drift.
|
||||
fn is_step(a: Anchor, b: Anchor) -> bool {
|
||||
let wall_ns = (i128::from(b.wall_us) - i128::from(a.wall_us)) * 1_000;
|
||||
let mach_ns = i128::from(b.mach_ns) - i128::from(a.mach_ns);
|
||||
(wall_ns - mach_ns).abs() > STEP_THRESHOLD_NS
|
||||
}
|
||||
|
||||
/// Returns the master clock time, in nanoseconds, of the wall clock time `wall_us`
|
||||
/// (microseconds since the Unix epoch), or `None` if the map has no anchors.
|
||||
///
|
||||
/// The result is never negative: a time that maps before the origin of the master clock is
|
||||
/// returned as zero. If the wall clock was stepped back, two segments can contain the same wall
|
||||
/// clock time; the segment earlier in master clock time is used.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::{Anchor, ClockMap};
|
||||
///
|
||||
/// // wall = master + 1000 s, with the wall clock running slightly fast between the anchors
|
||||
/// let map = ClockMap::new(vec![
|
||||
/// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 },
|
||||
/// Anchor { wall_us: 2_005_000_500, mach_ns: 1_005_000_000_000 },
|
||||
/// ]);
|
||||
///
|
||||
/// // halfway between them, interpolated
|
||||
/// assert_eq!(map.wall_to_mach(2_002_500_250), Some(1_002_500_000_000));
|
||||
///
|
||||
/// // outside them, extended from the nearer end at a constant offset
|
||||
/// assert_eq!(map.wall_to_mach(1_999_000_000), Some(999_000_000_000));
|
||||
/// assert_eq!(map.wall_to_mach(2_010_000_500), Some(1_010_000_000_000));
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn wall_to_mach(&self, wall_us: i64) -> Option<u64> {
|
||||
let (first, last) = (*self.anchors.first()?, *self.anchors.last()?);
|
||||
let extrapolate = |anchor: Anchor| {
|
||||
let mach = i128::from(wall_us) - anchor.offset_us();
|
||||
(mach * 1_000).max(0) as u64
|
||||
};
|
||||
|
||||
if self.anchors.len() == 1 {
|
||||
return Some(extrapolate(first));
|
||||
}
|
||||
|
||||
for pair in self.anchors.windows(2) {
|
||||
let (a, b) = (pair[0], pair[1]);
|
||||
let (lo, hi) = (a.wall_us.min(b.wall_us), a.wall_us.max(b.wall_us));
|
||||
if wall_us < lo || wall_us > hi {
|
||||
continue;
|
||||
}
|
||||
|
||||
if Self::is_step(a, b) {
|
||||
// we cannot know when inside the segment the step happened, so trust whichever
|
||||
// end is closer in wall time
|
||||
let nearest = if (wall_us - a.wall_us).abs() <= (wall_us - b.wall_us).abs() {
|
||||
a
|
||||
} else {
|
||||
b
|
||||
};
|
||||
return Some(extrapolate(nearest));
|
||||
}
|
||||
|
||||
let wall_span = i128::from(b.wall_us) - i128::from(a.wall_us);
|
||||
if wall_span == 0 {
|
||||
return Some(a.mach_ns);
|
||||
}
|
||||
|
||||
let mach_span = i128::from(b.mach_ns) - i128::from(a.mach_ns);
|
||||
let into = i128::from(wall_us) - i128::from(a.wall_us);
|
||||
return Some((i128::from(a.mach_ns) + into * mach_span / wall_span).max(0) as u64);
|
||||
}
|
||||
|
||||
// outside every segment: extend from whichever end is nearest in wall time
|
||||
let nearest = if (wall_us - first.wall_us).abs() <= (wall_us - last.wall_us).abs() {
|
||||
first
|
||||
} else {
|
||||
last
|
||||
};
|
||||
Some(extrapolate(nearest))
|
||||
}
|
||||
|
||||
/// Returns the wall clock time, in microseconds since the Unix epoch, of the master clock time
|
||||
/// `mach_ns`, or `None` if the map has no anchors.
|
||||
///
|
||||
/// The master clock has a resolution finer than a microsecond, and the result is truncated to
|
||||
/// whole microseconds. Within a segment that holds no step, a wall clock time taken through
|
||||
/// [`wall_to_mach`](ClockMap::wall_to_mach) and back comes back within 1 microsecond (the test
|
||||
/// `roundtrips_within_a_microsecond`); that is not guaranteed across a step.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::clock::{Anchor, ClockMap};
|
||||
///
|
||||
/// let map = ClockMap::new(vec![
|
||||
/// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 },
|
||||
/// Anchor { wall_us: 2_005_000_000, mach_ns: 1_005_000_000_000 },
|
||||
/// ]);
|
||||
///
|
||||
/// let wall_us = map.mach_to_wall(1_002_345_678_000).expect("the map has anchors");
|
||||
/// assert_eq!(wall_us, 2_002_345_678);
|
||||
///
|
||||
/// let back = map.wall_to_mach(wall_us).expect("the map has anchors");
|
||||
/// assert_eq!(back, 1_002_345_678_000);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn mach_to_wall(&self, mach_ns: u64) -> Option<i64> {
|
||||
let (first, last) = (*self.anchors.first()?, *self.anchors.last()?);
|
||||
let extrapolate = |anchor: Anchor| {
|
||||
let wall = i128::from(mach_ns / 1_000) + anchor.offset_us();
|
||||
wall as i64
|
||||
};
|
||||
|
||||
if mach_ns <= first.mach_ns {
|
||||
return Some(extrapolate(first));
|
||||
}
|
||||
|
||||
if mach_ns >= last.mach_ns {
|
||||
return Some(extrapolate(last));
|
||||
}
|
||||
|
||||
for pair in self.anchors.windows(2) {
|
||||
let (a, b) = (pair[0], pair[1]);
|
||||
if mach_ns < a.mach_ns || mach_ns > b.mach_ns {
|
||||
continue;
|
||||
}
|
||||
|
||||
if Self::is_step(a, b) {
|
||||
let nearest = if mach_ns - a.mach_ns <= b.mach_ns - mach_ns {
|
||||
a
|
||||
} else {
|
||||
b
|
||||
};
|
||||
return Some(extrapolate(nearest));
|
||||
}
|
||||
|
||||
let mach_span = i128::from(b.mach_ns) - i128::from(a.mach_ns);
|
||||
let wall_span = i128::from(b.wall_us) - i128::from(a.wall_us);
|
||||
let into = i128::from(mach_ns) - i128::from(a.mach_ns);
|
||||
return Some((i128::from(a.wall_us) + into * wall_span / mach_span) as i64);
|
||||
}
|
||||
|
||||
Some(extrapolate(last))
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn anchor(wall_s: i64, mach_s: u64) -> Anchor {
|
||||
Anchor {
|
||||
wall_us: wall_s * 1_000_000,
|
||||
mach_ns: mach_s * 1_000_000_000,
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_counters_frequency_is_a_timebase() {
|
||||
// the usual QueryPerformanceFrequency: 10 MHz, 100 ns a tick
|
||||
let ten_mhz = Timebase::from_frequency(10_000_000);
|
||||
assert_eq!(
|
||||
ten_mhz,
|
||||
Timebase {
|
||||
numer: 100,
|
||||
denom: 1
|
||||
}
|
||||
);
|
||||
assert_eq!(ten_mhz.ticks_to_ns(10_000_000), 1_000_000_000);
|
||||
assert_eq!(ten_mhz.ns_to_ticks(1_000_000_000), 10_000_000);
|
||||
|
||||
// one that does not divide evenly
|
||||
let odd = Timebase::from_frequency(3_579_545);
|
||||
let one_second = odd.ns_to_ticks(1_000_000_000);
|
||||
assert!(
|
||||
(3_579_544..=3_579_546).contains(&one_second),
|
||||
"{one_second}"
|
||||
);
|
||||
|
||||
// a nanosecond counter, and a nonsense zero, are both fine
|
||||
assert_eq!(
|
||||
Timebase::from_frequency(1_000_000_000),
|
||||
Timebase { numer: 1, denom: 1 }
|
||||
);
|
||||
assert_eq!(Timebase::from_frequency(0).ticks_to_ns(5), 5_000_000_000);
|
||||
|
||||
// faster than u32 can hold: still close
|
||||
let fast = Timebase::from_frequency(10_000_000_000);
|
||||
assert!(fast.ticks_to_ns(10_000_000_000).abs_diff(1_000_000_000) < 10_000_000);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn timebase_roundtrip() {
|
||||
let tb = Timebase {
|
||||
numer: 125,
|
||||
denom: 3,
|
||||
};
|
||||
let ns = tb.ticks_to_ns(24_000_000);
|
||||
assert_eq!(ns, 1_000_000_000);
|
||||
assert_eq!(tb.ns_to_ticks(ns), 24_000_000);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mach_is_monotonic_and_wall_is_sane() {
|
||||
let a = mono_now_ns();
|
||||
let b = mono_now_ns();
|
||||
assert!(b >= a);
|
||||
// after 2020 and before 2100
|
||||
assert!(wall_now_us() > 1_577_836_800_000_000);
|
||||
assert!(wall_now_us() < 4_102_444_800_000_000);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn anchor_sample_is_close_to_now() {
|
||||
let anchor = Anchor::sample();
|
||||
let now = wall_now_us();
|
||||
assert!((now - anchor.wall_us).abs() < 50_000);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn interpolates_between_anchors() {
|
||||
// wall = mach + 1000s, with the wall clock running 100ppm fast over the segment
|
||||
let a = anchor(2000, 1000);
|
||||
let b = Anchor {
|
||||
wall_us: 2005 * 1_000_000 + 500,
|
||||
mach_ns: 1005 * 1_000_000_000,
|
||||
};
|
||||
let map = ClockMap::new(vec![a, b]);
|
||||
|
||||
let mach = map.wall_to_mach(2_002_500_000 + 250).expect("mach");
|
||||
assert_eq!(mach, 1_002_500_000_000);
|
||||
|
||||
let wall = map.mach_to_wall(1_002_500_000_000).expect("wall");
|
||||
assert_eq!(wall, 2_002_500_000 + 250);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn roundtrips_within_a_microsecond() {
|
||||
let map = ClockMap::new(vec![
|
||||
anchor(2000, 1000),
|
||||
anchor(2005, 1005),
|
||||
anchor(2010, 1010),
|
||||
]);
|
||||
for wall in [2_000_123_456, 2_004_999_999, 2_007_777_777, 2_009_000_001] {
|
||||
let mach = map.wall_to_mach(wall).expect("mach");
|
||||
let back = map.mach_to_wall(mach).expect("wall");
|
||||
assert!((back - wall).abs() <= 1, "{wall} -> {mach} -> {back}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn extrapolates_outside_the_anchor_range() {
|
||||
let map = ClockMap::new(vec![anchor(2000, 1000), anchor(2005, 1005)]);
|
||||
assert_eq!(
|
||||
map.wall_to_mach(1_999_000_000),
|
||||
Some(999_000_000_000),
|
||||
"before the first anchor"
|
||||
);
|
||||
assert_eq!(
|
||||
map.wall_to_mach(2_010_000_000),
|
||||
Some(1_010_000_000_000),
|
||||
"after the last anchor"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn handles_a_clock_step() {
|
||||
// the wall clock jumps forward 30s between the second and third anchors (an NTP step, or
|
||||
// the machine slept while mach time was paused)
|
||||
let map = ClockMap::new(vec![
|
||||
anchor(2000, 1000),
|
||||
anchor(2005, 1005),
|
||||
anchor(2040, 1010),
|
||||
]);
|
||||
|
||||
// before the step the offset is 1000s
|
||||
assert_eq!(map.wall_to_mach(2_001_000_000), Some(1_001_000_000_000));
|
||||
// after the step the offset is 1030s
|
||||
assert_eq!(map.wall_to_mach(2_039_000_000), Some(1_009_000_000_000));
|
||||
// and mach -> wall agrees on both sides
|
||||
assert_eq!(map.mach_to_wall(1_001_000_000_000), Some(2_001_000_000));
|
||||
assert_eq!(map.mach_to_wall(1_009_000_000_000), Some(2_039_000_000));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn single_anchor_is_a_constant_offset() {
|
||||
let map = ClockMap::new(vec![anchor(2000, 1000)]);
|
||||
assert_eq!(map.wall_to_mach(2_003_000_000), Some(1_003_000_000_000));
|
||||
assert_eq!(map.mach_to_wall(1_003_000_000_000), Some(2_003_000_000));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_jump_detector_ignores_ordinary_time_passing() {
|
||||
let mut detector = JumpDetector::new(anchor(2000, 1000));
|
||||
// 50 ms later on both clocks, with a little drift
|
||||
let tick = |wall_us: i64, mach_ns: u64| Anchor { wall_us, mach_ns };
|
||||
assert_eq!(
|
||||
detector.observe(tick(2_000_050_010, 1_000_050_000_000)),
|
||||
None
|
||||
);
|
||||
// a long but consistent interval (the process was merely descheduled)
|
||||
assert_eq!(
|
||||
detector.observe(tick(2_030_050_010, 1_030_050_000_000)),
|
||||
None
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_jump_detector_notices_sleep_and_brackets_it() {
|
||||
let mut detector = JumpDetector::new(anchor(2000, 1000));
|
||||
let before = Anchor {
|
||||
wall_us: 2_000_050_000,
|
||||
mach_ns: 1_000_050_000_000,
|
||||
};
|
||||
assert_eq!(detector.observe(before), None);
|
||||
|
||||
// the lid is closed for 3600 s: wall time moves on, mach time barely does
|
||||
let after = Anchor {
|
||||
wall_us: 2_000_100_000 + 3_600_000_000,
|
||||
mach_ns: 1_000_100_000_000,
|
||||
};
|
||||
let jump = detector.observe(after).expect("a jump");
|
||||
assert!((jump.seconds - 3_600.0).abs() < 0.01, "{}", jump.seconds);
|
||||
assert_eq!(
|
||||
jump.before, before,
|
||||
"the last good pairing before the sleep"
|
||||
);
|
||||
assert_eq!(jump.after, after);
|
||||
|
||||
// and with those two anchors the map is right on both sides of the sleep
|
||||
let map = ClockMap::new(vec![jump.before, jump.after]);
|
||||
assert_eq!(map.wall_to_mach(2_000_050_000), Some(1_000_050_000_000));
|
||||
assert_eq!(
|
||||
map.wall_to_mach(2_000_100_000 + 3_600_000_000),
|
||||
Some(1_000_100_000_000)
|
||||
);
|
||||
assert_eq!(
|
||||
map.wall_to_mach(2_000_100_000 + 3_600_000_000 + 2_000_000),
|
||||
Some(1_000_100_000_000 + 2_000_000_000),
|
||||
"two seconds after waking"
|
||||
);
|
||||
|
||||
// the detector carries on from the new position
|
||||
assert_eq!(
|
||||
detector.observe(Anchor {
|
||||
wall_us: after.wall_us + 50_000,
|
||||
mach_ns: after.mach_ns + 50_000_000
|
||||
}),
|
||||
None
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_jump_detector_notices_the_clock_stepping_back() {
|
||||
let mut detector = JumpDetector::new(anchor(2000, 1000));
|
||||
let jump = detector
|
||||
.observe(Anchor {
|
||||
wall_us: 2_000_050_000 - 30_000_000,
|
||||
mach_ns: 1_000_050_000_000,
|
||||
})
|
||||
.expect("a jump");
|
||||
assert!(
|
||||
jump.seconds < -29.0 && jump.seconds > -31.0,
|
||||
"{}",
|
||||
jump.seconds
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn empty_map_has_no_answer() {
|
||||
let map = ClockMap::default();
|
||||
assert_eq!(map.wall_to_mach(1), None);
|
||||
assert_eq!(map.mach_to_wall(1), None);
|
||||
}
|
||||
}
|
||||
@@ -8,3 +8,52 @@
|
||||
//! This crate is the library behind the `komorebi-recorder` command. A reader who wants to run it should start with the
|
||||
//! [README](https://github.com/LGUG2Z/komorebi-recorder#readme); this documentation is for someone who is changing it,
|
||||
//! or reading a session directory from a program of their own.
|
||||
//!
|
||||
//! # The model
|
||||
//!
|
||||
//! Two things vary independently. The _host_ is the OS the recorder runs on, and everything that differs by it is behind
|
||||
//! [`platform`]. The _flavor_ is the komorebi being recorded, komorebi for Mac or komorebi for Windows, and everything
|
||||
//! that differs by it is behind a trait in the analysis. A session records both, so a session recorded on one host can
|
||||
//! be read on the other.
|
||||
//!
|
||||
//! Every record in a session is stamped on one monotonic clock, the _master clock_ ([`clock`]). Video frames and the OS
|
||||
//! trace are already on it; komorebi's log lines carry wall-clock time and are mapped onto it with paired readings of
|
||||
//! both clocks. For example, a log line stamped five seconds after the first of two anchors that are ten seconds apart
|
||||
//! is five seconds after it on the master clock too:
|
||||
//!
|
||||
//! ```rust
|
||||
//! use komorebi_recorder::clock::Anchor;
|
||||
//! use komorebi_recorder::clock::ClockMap;
|
||||
//!
|
||||
//! let map = ClockMap::new(vec![
|
||||
//! Anchor { wall_us: 1_000_000, mach_ns: 5_000_000_000 },
|
||||
//! Anchor { wall_us: 11_000_000, mach_ns: 15_000_000_000 },
|
||||
//! ]);
|
||||
//!
|
||||
//! assert_eq!(map.wall_to_mach(6_000_000), Some(10_000_000_000));
|
||||
//! ```
|
||||
//!
|
||||
//! # Where to start
|
||||
//!
|
||||
//! The modules, from the ones everything else uses to the ones that use everything:
|
||||
//!
|
||||
//! | module | what it is |
|
||||
//! |---|---|
|
||||
//! | [`timecode`] | parsing and printing video timecodes |
|
||||
//! | [`clock`] | the master clock, anchors and the map between the wall clock and the master clock |
|
||||
//! | [`platform`] | everything that differs by host, behind one facade |
|
||||
//!
|
||||
//! # What is not supported
|
||||
//!
|
||||
//! The recorder does not change komorebi's log level or lifecycle, it does not need `sudo` and changes no SIP setting on
|
||||
//! a Mac, and it does not trace system calls. A session records what komorebi, the OS trace and the screen said, and
|
||||
//! nothing from before the recording began.
|
||||
//!
|
||||
//! # Platform support
|
||||
//!
|
||||
//! The Windows host is type-checked and cross-built from a Mac and built on Windows in CI, and has never been run. See
|
||||
//! [`platform`] for what each host provides.
|
||||
|
||||
pub mod clock;
|
||||
pub mod platform;
|
||||
pub mod timecode;
|
||||
@@ -0,0 +1,112 @@
|
||||
//! The master clock on macOS: `mach_absolute_time`, the clock `ScreenCaptureKit` and the unified
|
||||
//! log already use.
|
||||
//!
|
||||
//! Every time in a session is nanoseconds on this clock (see [`crate::clock`]). It counts ticks of
|
||||
//! a size the OS reports ([`timebase`]) and pauses while the machine sleeps, so a sleep shows up as
|
||||
//! the wall clock moving on while this one does not. [`reference_clocks`] reads the clock that does
|
||||
//! keep counting through a sleep.
|
||||
//!
|
||||
//! The same items exist on Windows, where the clock is `QueryPerformanceCounter`.
|
||||
|
||||
use crate::clock::Timebase;
|
||||
use crate::platform::ClockKind;
|
||||
use std::sync::OnceLock;
|
||||
|
||||
/// Which clock the master clock is: [`ClockKind::Mach`], recorded as `host.clock` in the manifest.
|
||||
pub const KIND: ClockKind = ClockKind::Mach;
|
||||
|
||||
#[repr(C)]
|
||||
struct MachTimebaseInfo {
|
||||
numer: u32,
|
||||
denom: u32,
|
||||
}
|
||||
|
||||
// `libc` marks its mach bindings deprecated in favour of the `mach2` crate; these two symbols
|
||||
// are all we need from libSystem, so declare them directly instead of adding a dependency
|
||||
unsafe extern "C" {
|
||||
fn mach_absolute_time() -> u64;
|
||||
fn mach_continuous_time() -> u64;
|
||||
fn mach_timebase_info(info: *mut MachTimebaseInfo) -> i32;
|
||||
}
|
||||
|
||||
/// Returns what one tick of [`now_ticks`] is worth, as `numer / denom` nanoseconds.
|
||||
///
|
||||
/// It is read from `mach_timebase_info` once and kept. If the OS reports no usable timebase (which
|
||||
/// a Mac that can run this always does), it is `1 / 1`.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::platform::clock::{now_ns, now_ticks, timebase};
|
||||
///
|
||||
/// // the master clock is the tick count scaled by the timebase, and never goes backwards
|
||||
/// let ns = timebase().ticks_to_ns(now_ticks());
|
||||
/// assert!(now_ns() >= ns);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn timebase() -> Timebase {
|
||||
static TIMEBASE: OnceLock<Timebase> = OnceLock::new();
|
||||
*TIMEBASE.get_or_init(|| {
|
||||
let mut info = MachTimebaseInfo { numer: 0, denom: 0 };
|
||||
// SAFETY: `info` is a valid out pointer for the duration of the call
|
||||
let status = unsafe { mach_timebase_info(&raw mut info) };
|
||||
if status != 0 || info.denom == 0 {
|
||||
// every Mac that can run this has a valid timebase; 1/1 is the safe identity
|
||||
return Timebase { numer: 1, denom: 1 };
|
||||
}
|
||||
|
||||
Timebase {
|
||||
numer: info.numer,
|
||||
denom: info.denom,
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/// Returns the raw tick count of `mach_absolute_time`, which pauses while the machine sleeps.
|
||||
#[must_use]
|
||||
pub fn now_ticks() -> u64 {
|
||||
// SAFETY: no preconditions
|
||||
unsafe { mach_absolute_time() }
|
||||
}
|
||||
|
||||
/// Returns nanoseconds on the host monotonic clock: the master clock every record in a session is
|
||||
/// on. It is [`now_ticks`] scaled by [`timebase`], so it pauses while the machine sleeps.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::platform::clock::now_ns;
|
||||
///
|
||||
/// let first = now_ns();
|
||||
/// let second = now_ns();
|
||||
/// assert!(second >= first);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn now_ns() -> u64 {
|
||||
timebase().ticks_to_ns(now_ticks())
|
||||
}
|
||||
|
||||
/// Returns the host's other clocks, to be read beside the master clock: one,
|
||||
/// `mach_continuous_time`, which counts the time the machine spends asleep, unlike the master
|
||||
/// clock.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::platform::clock::reference_clocks;
|
||||
///
|
||||
/// let clocks = reference_clocks();
|
||||
/// assert_eq!(clocks.len(), 1);
|
||||
/// assert_eq!(clocks[0].name, "mach_continuous_time");
|
||||
/// assert!(clocks[0].counts_sleep);
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn reference_clocks() -> Vec<crate::clock::ReferenceClock> {
|
||||
// SAFETY: no preconditions
|
||||
let ticks = unsafe { mach_continuous_time() };
|
||||
vec![crate::clock::ReferenceClock {
|
||||
name: "mach_continuous_time".to_string(),
|
||||
counts_sleep: true,
|
||||
ns: timebase().ticks_to_ns(ticks),
|
||||
}]
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
//! The macOS host: what the [`platform`](crate::platform) facade is made of on a Mac.
|
||||
//!
|
||||
//! | module | built on |
|
||||
//! |---|---|
|
||||
//! | `apps` | the window server's window list (`CGWindowListCopyWindowInfo`) |
|
||||
//! | `capture` | `ScreenCaptureKit` and `AVFoundation` (in `crate::capture::sck`) |
|
||||
//! | `clock` | `mach_absolute_time` |
|
||||
//! | `power` | nothing: a Mac's sleep is found from the clocks, so there is no watcher |
|
||||
//! | `process` | process groups and `SIGTERM` |
|
||||
//! | `session` | the CoreGraphics session dictionary |
|
||||
//! | `shell` | `open`, `osascript` and `sw_vers` |
|
||||
//! | `trace` | nothing: the OS trace is `log stream` children (`crate::sources::oslog`), not taps |
|
||||
//!
|
||||
//! Nothing here is public API except through the facade: this module is private, and the facade
|
||||
//! re-exports its submodules under the same names on every host.
|
||||
|
||||
pub mod clock;
|
||||
pub mod shell;
|
||||
|
||||
/// Does nothing: a Mac needs nothing done once at the start of `main`. (Windows makes the process
|
||||
/// DPI aware.)
|
||||
pub fn init() {}
|
||||
@@ -0,0 +1,72 @@
|
||||
//! Showing a folder, asking for one, and naming the OS.
|
||||
//!
|
||||
//! The recorder window offers to show a finished session in the file manager, the viewer asks for
|
||||
//! a session folder, and the manifest records the OS version. On macOS these are `open`,
|
||||
//! `osascript` and `sw_vers`; the same items exist on Windows.
|
||||
|
||||
use std::path::Path;
|
||||
use std::path::PathBuf;
|
||||
use std::process::Command;
|
||||
|
||||
/// What the OS calls its file manager, for button labels: `Finder`.
|
||||
pub const FILE_MANAGER: &str = "Finder";
|
||||
|
||||
/// Returns the OS version as `sw_vers -productVersion` prints it, e.g. `26.0`, or `None` if that
|
||||
/// cannot be run or prints nothing. On Windows it is `major.minor.build`.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::platform::shell::{FILE_MANAGER, os_version};
|
||||
///
|
||||
/// assert_eq!(FILE_MANAGER, "Finder");
|
||||
/// if let Some(version) = os_version() {
|
||||
/// assert!(version.chars().all(|c| c.is_ascii_digit() || c == '.'), "{version}");
|
||||
/// }
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn os_version() -> Option<String> {
|
||||
let output = Command::new("/usr/bin/sw_vers")
|
||||
.arg("-productVersion")
|
||||
.output()
|
||||
.ok()?;
|
||||
let version = String::from_utf8(output.stdout).ok()?.trim().to_string();
|
||||
(!version.is_empty()).then_some(version)
|
||||
}
|
||||
|
||||
/// Shows `path` in the file manager.
|
||||
///
|
||||
/// This runs `open path` and does not wait for it, and a failure to start it is not reported. A
|
||||
/// folder opens in Finder. A file opens in its default application, not selected in Finder (`open
|
||||
/// -R` would select it); the recorder only passes folders. On Windows a file is selected in its
|
||||
/// folder.
|
||||
///
|
||||
/// This starts another program, so it has no doctest.
|
||||
pub fn reveal(path: &Path) {
|
||||
let _ = Command::new("open").arg(path).spawn();
|
||||
}
|
||||
|
||||
/// Asks the user for a folder with the system's own dialog, and blocks until they answer.
|
||||
///
|
||||
/// Returns the folder they chose, or `None` if they canceled, the dialog could not be shown, or
|
||||
/// the path came back empty. `prompt` is the dialog's prompt text. It is not escaped: it is placed
|
||||
/// inside an `AppleScript` string, so it should not contain `"` or `\`.
|
||||
///
|
||||
/// This shows a dialog, so it has no doctest.
|
||||
#[must_use]
|
||||
pub fn pick_folder(prompt: &str) -> Option<PathBuf> {
|
||||
let output = Command::new("osascript")
|
||||
.args([
|
||||
"-e",
|
||||
&format!("POSIX path of (choose folder with prompt \"{prompt}\")"),
|
||||
])
|
||||
.output()
|
||||
.ok()?;
|
||||
|
||||
output
|
||||
.status
|
||||
.success()
|
||||
.then(|| String::from_utf8_lossy(&output.stdout).trim().to_string())
|
||||
.filter(|path| !path.is_empty())
|
||||
.map(PathBuf::from)
|
||||
}
|
||||
@@ -0,0 +1,181 @@
|
||||
//! Everything that differs by the OS the recorder runs on.
|
||||
//!
|
||||
//! The rest of the crate never names a system API. It asks this module for the handful of things
|
||||
//! that are not portable, and each host provides them:
|
||||
//!
|
||||
//! | module | what it answers |
|
||||
//! |---|---|
|
||||
//! | [`clock`] | the master monotonic clock and its tick size |
|
||||
//! | [`shell`] | the OS version, and (for the recorder window) showing a folder and asking for one |
|
||||
//!
|
||||
//! A third host, `unsupported`, builds on anything else so that the investigation commands (which
|
||||
//! only read a session directory) still work on a Linux agent box; recording there says so.
|
||||
//!
|
||||
//! # The host axis
|
||||
//!
|
||||
//! This is the *host* axis: what the recorder is running on.
|
||||
//! Which komorebi produced a session is a separate axis, the *flavor*: a session recorded on
|
||||
//! Windows can be investigated on a Mac, and the [`Host`] a session was recorded on is part of its
|
||||
//! manifest.
|
||||
//!
|
||||
//! # Adding a function
|
||||
//!
|
||||
//! A function that the rest of the crate calls as `platform::<module>::<name>` has to exist, with
|
||||
//! the same signature, in `macos/<module>.rs`, `win/<module>.rs` and `unsupported.rs`. The
|
||||
//! compiler enforces that for the host being built, and for no other: the Windows host is built
|
||||
//! from a Mac by `just check-windows` and by CI, and `unsupported` is built only on a third OS,
|
||||
//! where nothing in CI builds it.
|
||||
|
||||
#[cfg(target_os = "macos")]
|
||||
mod macos;
|
||||
#[cfg(target_os = "macos")]
|
||||
use macos as imp;
|
||||
|
||||
#[cfg(not(any(target_os = "macos", windows)))]
|
||||
mod unsupported;
|
||||
#[cfg(not(any(target_os = "macos", windows)))]
|
||||
use unsupported as imp;
|
||||
|
||||
// not `windows`: that would be ambiguous with the `windows` crate in every `use` of this module
|
||||
#[cfg(windows)]
|
||||
mod win;
|
||||
#[cfg(windows)]
|
||||
use win as imp;
|
||||
|
||||
pub use imp::clock;
|
||||
pub use imp::shell;
|
||||
|
||||
/// Things the OS wants done once, first thing in `main`: on Windows, becoming DPI aware so that
|
||||
/// sizes and positions are in physical pixels. Nothing on other hosts.
|
||||
pub fn init() {
|
||||
imp::init();
|
||||
}
|
||||
|
||||
use schemars::JsonSchema;
|
||||
use serde::Deserialize;
|
||||
use serde::Serialize;
|
||||
|
||||
/// Which master clock a session's `*_mach_ns` values are on.
|
||||
///
|
||||
/// The field names keep their historical `mach_` spelling so that sessions stay readable by every
|
||||
/// build of the tool; what they hold is "nanoseconds on the host's monotonic clock", and this says
|
||||
/// which clock that was.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
|
||||
#[serde(rename_all = "lowercase")]
|
||||
pub enum ClockKind {
|
||||
/// `mach_absolute_time`: pauses while the machine sleeps.
|
||||
Mach,
|
||||
/// `QueryPerformanceCounter`.
|
||||
Qpc,
|
||||
/// A host with no capture, which still needs some monotonic clock to run on.
|
||||
Std,
|
||||
}
|
||||
|
||||
/// What a session was recorded on.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::platform::ClockKind;
|
||||
/// use komorebi_recorder::platform::Host;
|
||||
///
|
||||
/// // a session from before hosts were recorded can only have been recorded on a Mac
|
||||
/// let host = Host::legacy_macos(Some("26.0".to_string()));
|
||||
/// assert!(host.is_macos() && !host.is_windows());
|
||||
/// assert_eq!(host.clock, ClockKind::Mach);
|
||||
/// assert_eq!(host.describe(), "macOS 26.0");
|
||||
/// ```
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
|
||||
pub struct Host {
|
||||
/// `macos`, `windows`, ...
|
||||
pub os: String,
|
||||
/// The CPU architecture, as Rust names it (`aarch64`, `x86_64`).
|
||||
pub arch: String,
|
||||
/// The OS version, if the host could say (`26.0` on macOS, `10.0.26100` on Windows).
|
||||
pub os_version: Option<String>,
|
||||
/// Which clock the session's `*_mach_ns` values are on.
|
||||
pub clock: ClockKind,
|
||||
}
|
||||
|
||||
impl Host {
|
||||
/// The machine this process is running on.
|
||||
#[must_use]
|
||||
pub fn current() -> Self {
|
||||
Self {
|
||||
os: std::env::consts::OS.to_string(),
|
||||
arch: std::env::consts::ARCH.to_string(),
|
||||
os_version: shell::os_version(),
|
||||
clock: clock::KIND,
|
||||
}
|
||||
}
|
||||
|
||||
/// What a session from before hosts were recorded was recorded on: it can only have been a Mac.
|
||||
#[must_use]
|
||||
pub fn legacy_macos(os_version: Option<String>) -> Self {
|
||||
Self {
|
||||
os: "macos".to_string(),
|
||||
arch: "aarch64".to_string(),
|
||||
os_version,
|
||||
clock: ClockKind::Mach,
|
||||
}
|
||||
}
|
||||
|
||||
#[must_use]
|
||||
/// Returns `true` if and only if this is macOS.
|
||||
pub fn is_macos(&self) -> bool {
|
||||
self.os == "macos"
|
||||
}
|
||||
|
||||
#[must_use]
|
||||
/// Returns `true` if and only if this is Windows.
|
||||
pub fn is_windows(&self) -> bool {
|
||||
self.os == "windows"
|
||||
}
|
||||
|
||||
/// `macOS 26.0`, `windows 10.0.26100`: for prose.
|
||||
#[must_use]
|
||||
pub fn describe(&self) -> String {
|
||||
let os = match self.os.as_str() {
|
||||
"macos" => "macOS",
|
||||
"windows" => "Windows",
|
||||
other => other,
|
||||
};
|
||||
match &self.os_version {
|
||||
Some(version) => format!("{os} {version}"),
|
||||
None => os.to_string(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn a_host_reads_back_what_it_wrote() {
|
||||
let host = Host::current();
|
||||
let text = serde_json::to_string(&host).expect("serialize");
|
||||
let back: Host = serde_json::from_str(&text).expect("parse");
|
||||
assert_eq!(back, host);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_clock_kind_is_spelled_in_lowercase() {
|
||||
assert_eq!(
|
||||
serde_json::to_string(&ClockKind::Qpc).expect("serialize"),
|
||||
r#""qpc""#
|
||||
);
|
||||
assert_eq!(
|
||||
serde_json::to_string(&ClockKind::Mach).expect("serialize"),
|
||||
r#""mach""#
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_session_from_before_hosts_were_recorded_was_a_mac() {
|
||||
let host = Host::legacy_macos(Some("26.0".into()));
|
||||
assert!(host.is_macos());
|
||||
assert_eq!(host.describe(), "macOS 26.0");
|
||||
assert_eq!(host.clock, ClockKind::Mach);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
//! Any other OS: enough to build and to investigate a session directory that was recorded
|
||||
//! elsewhere (the commands that only read files), but not to record one.
|
||||
|
||||
/// Nothing to do first.
|
||||
pub fn init() {}
|
||||
|
||||
/// The master clock, which here is Rust's monotonic [`Instant`].
|
||||
pub mod clock {
|
||||
use crate::clock::Timebase;
|
||||
use crate::platform::ClockKind;
|
||||
use std::sync::OnceLock;
|
||||
use std::time::Instant;
|
||||
|
||||
/// The clock a session recorded here is on: Rust's [`Instant`].
|
||||
pub const KIND: ClockKind = ClockKind::Std;
|
||||
|
||||
/// Returns the identity timebase: [`now_ns`] is already in nanoseconds.
|
||||
#[must_use]
|
||||
pub fn timebase() -> Timebase {
|
||||
Timebase { numer: 1, denom: 1 }
|
||||
}
|
||||
|
||||
/// Returns no other clocks.
|
||||
#[must_use]
|
||||
pub fn reference_clocks() -> Vec<crate::clock::ReferenceClock> {
|
||||
Vec::new()
|
||||
}
|
||||
|
||||
/// Nanoseconds since the first reading in this process, offset so that none is ever zero
|
||||
/// (zero means "not yet" in the capture counters).
|
||||
#[must_use]
|
||||
pub fn now_ns() -> u64 {
|
||||
static START: OnceLock<Instant> = OnceLock::new();
|
||||
START.get_or_init(Instant::now).elapsed().as_nanos() as u64 + 1_000_000_000
|
||||
}
|
||||
}
|
||||
|
||||
/// Showing a folder, asking for one, and naming the OS, with what this host can offer.
|
||||
pub mod shell {
|
||||
use std::path::Path;
|
||||
use std::path::PathBuf;
|
||||
|
||||
/// What this host calls its file manager, for button labels.
|
||||
pub const FILE_MANAGER: &str = "file manager";
|
||||
|
||||
/// Returns `None`: this host cannot say which version it is.
|
||||
#[must_use]
|
||||
pub fn os_version() -> Option<String> {
|
||||
None
|
||||
}
|
||||
|
||||
/// Asks `xdg-open` to show `path`.
|
||||
pub fn reveal(path: &Path) {
|
||||
let _ = std::process::Command::new("xdg-open").arg(path).spawn();
|
||||
}
|
||||
|
||||
/// Returns `None`: this host has no dialog to ask with.
|
||||
#[must_use]
|
||||
pub fn pick_folder(_prompt: &str) -> Option<PathBuf> {
|
||||
None
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
//! The master clock on Windows: `QueryPerformanceCounter`, the clock Windows.Graphics.Capture frame
|
||||
//! times are on.
|
||||
//!
|
||||
//! Every time in a session is nanoseconds on this clock (see [`crate::clock`]). It counts ticks of
|
||||
//! a size the OS reports ([`timebase`]). Whether it keeps counting while the machine sleeps is not
|
||||
//! assumed: `doctor --probe clock` measures it, using the two clocks of [`reference_clocks`], and
|
||||
//! the power watcher (`crate::platform::power`) says when a sleep happens either way.
|
||||
//!
|
||||
//! The same items exist on macOS, where the clock is `mach_absolute_time`.
|
||||
|
||||
use crate::clock::Timebase;
|
||||
use crate::platform::ClockKind;
|
||||
use std::sync::OnceLock;
|
||||
use windows::Win32::System::Performance::QueryPerformanceCounter;
|
||||
use windows::Win32::System::Performance::QueryPerformanceFrequency;
|
||||
use windows::Win32::System::WindowsProgramming::QueryInterruptTime;
|
||||
use windows::Win32::System::WindowsProgramming::QueryUnbiasedInterruptTimePrecise;
|
||||
|
||||
/// Which clock the master clock is: [`ClockKind::Qpc`], recorded as `host.clock` in the manifest.
|
||||
pub const KIND: ClockKind = ClockKind::Qpc;
|
||||
|
||||
/// Returns what one tick of [`now_ticks`] is worth, as `numer / denom` nanoseconds.
|
||||
///
|
||||
/// It is made from `QueryPerformanceFrequency` once and kept. If that cannot be read, which it
|
||||
/// cannot do on any Windows that runs this, the frequency is taken to be 10 MHz, which is what it
|
||||
/// is nearly everywhere.
|
||||
#[must_use]
|
||||
pub fn timebase() -> Timebase {
|
||||
static TIMEBASE: OnceLock<Timebase> = OnceLock::new();
|
||||
*TIMEBASE.get_or_init(|| {
|
||||
let mut frequency = 0_i64;
|
||||
// SAFETY: `frequency` is a valid out pointer for the duration of the call
|
||||
let known = unsafe { QueryPerformanceFrequency(&raw mut frequency) }.is_ok();
|
||||
// it cannot fail on any Windows that runs this; 10 MHz is what it says nearly everywhere
|
||||
Timebase::from_frequency(if known && frequency > 0 {
|
||||
frequency as u64
|
||||
} else {
|
||||
10_000_000
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
/// Returns the raw `QueryPerformanceCounter` tick count. A negative reading, which does not
|
||||
/// happen, is `0`.
|
||||
#[must_use]
|
||||
pub fn now_ticks() -> u64 {
|
||||
let mut ticks = 0_i64;
|
||||
// SAFETY: `ticks` is a valid out pointer for the duration of the call
|
||||
let _ = unsafe { QueryPerformanceCounter(&raw mut ticks) };
|
||||
ticks.max(0) as u64
|
||||
}
|
||||
|
||||
/// Returns nanoseconds on the host monotonic clock: the master clock every record in a session is
|
||||
/// on. It is [`now_ticks`] scaled by [`timebase`].
|
||||
#[must_use]
|
||||
pub fn now_ns() -> u64 {
|
||||
timebase().ticks_to_ns(now_ticks())
|
||||
}
|
||||
|
||||
/// Returns the host's other clocks, to be read beside the master clock: the two interrupt-time
|
||||
/// clocks.
|
||||
///
|
||||
/// `QueryInterruptTime` counts the time the machine is suspended and
|
||||
/// `QueryUnbiasedInterruptTimePrecise` does not. Both are read in 100 ns units and returned in
|
||||
/// nanoseconds. Which of them the performance counter behaves like is what decides how a sleep
|
||||
/// can be noticed.
|
||||
#[must_use]
|
||||
pub fn reference_clocks() -> Vec<crate::clock::ReferenceClock> {
|
||||
// SAFETY: no preconditions
|
||||
let (biased, unbiased) = unsafe { (QueryInterruptTime(), QueryUnbiasedInterruptTimePrecise()) };
|
||||
vec![
|
||||
crate::clock::ReferenceClock {
|
||||
name: "QueryInterruptTime".to_string(),
|
||||
counts_sleep: true,
|
||||
ns: biased.saturating_mul(100),
|
||||
},
|
||||
crate::clock::ReferenceClock {
|
||||
name: "QueryUnbiasedInterruptTimePrecise".to_string(),
|
||||
counts_sleep: false,
|
||||
ns: unbiased.saturating_mul(100),
|
||||
},
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
//! The Windows host: what the [`platform`](crate::platform) facade is made of on Windows.
|
||||
//!
|
||||
//! | module | built on |
|
||||
//! |---|---|
|
||||
//! | `apps` | `EnumWindows` and `GetWindowThreadProcessId` |
|
||||
//! | `capture` | monitor enumeration and per-monitor DPI; the capture itself is Windows.Graphics.Capture (in `crate::capture::wgc`) |
|
||||
//! | `clock` | `QueryPerformanceCounter` |
|
||||
//! | `media` | Windows Runtime and Media Foundation start-up, shared by the capture and the decoder |
|
||||
//! | `power` | a hidden window that is sent suspend, resume, lid, display and session messages |
|
||||
//! | `process` | process creation flags and `TerminateProcess` |
|
||||
//! | `session` | whether the input desktop can be opened |
|
||||
//! | `shell` | Explorer, the folder dialog and `RtlGetVersion` |
|
||||
//! | `trace` | a `WinEvent` hook and Event Log subscriptions (see `crate::sources::wintrace`) |
|
||||
//! | `window` | this program's own windows and the reads about any window |
|
||||
//!
|
||||
//! Nothing here is public API except through the facade: this module is private, and the facade
|
||||
//! re-exports its submodules (all but `window`, which the shared `platform::window` calls) under the
|
||||
//! same names as on the other hosts.
|
||||
//!
|
||||
//! This code is compiled only for Windows. From another host it is type-checked and linted with
|
||||
//! `just check-windows`, and the checklist for running it on a real machine is
|
||||
//! `docs/dev/windows-checkpoints.md`.
|
||||
|
||||
pub mod clock;
|
||||
pub mod shell;
|
||||
|
||||
/// Does what Windows needs once, first thing in `main`: makes the process per-monitor DPI aware
|
||||
/// ([`capture::become_per_monitor_dpi_aware`]), so that every size and position it reads is in
|
||||
/// physical pixels, as komorebi's are. A Mac needs nothing here.
|
||||
pub fn init() {
|
||||
// Without this Windows lies to us about sizes: a display scaled to 150 % reads as smaller than
|
||||
// it is, and komorebi's rects (which are physical pixels) would not match ours.
|
||||
}
|
||||
@@ -0,0 +1,111 @@
|
||||
//! Showing a folder, asking for one, and naming the OS.
|
||||
//!
|
||||
//! The recorder window offers to show a finished session in the file manager, the viewer asks for
|
||||
//! a session folder, and the manifest records the OS version. On Windows these are Explorer, the
|
||||
//! common file dialog and `RtlGetVersion`; the same items exist on macOS.
|
||||
|
||||
use std::path::Path;
|
||||
use std::path::PathBuf;
|
||||
use std::process::Command;
|
||||
use windows::Wdk::System::SystemServices::RtlGetVersion;
|
||||
use windows::Win32::System::Com::CLSCTX_INPROC_SERVER;
|
||||
use windows::Win32::System::Com::COINIT_APARTMENTTHREADED;
|
||||
use windows::Win32::System::Com::CoCreateInstance;
|
||||
use windows::Win32::System::Com::CoInitializeEx;
|
||||
use windows::Win32::System::Com::CoTaskMemFree;
|
||||
use windows::Win32::System::Com::CoUninitialize;
|
||||
use windows::Win32::System::SystemInformation::OSVERSIONINFOW;
|
||||
use windows::Win32::UI::Shell::FOS_FORCEFILESYSTEM;
|
||||
use windows::Win32::UI::Shell::FOS_PICKFOLDERS;
|
||||
use windows::Win32::UI::Shell::FileOpenDialog;
|
||||
use windows::Win32::UI::Shell::IFileOpenDialog;
|
||||
use windows::Win32::UI::Shell::SIGDN_FILESYSPATH;
|
||||
use windows::core::PCWSTR;
|
||||
|
||||
/// What the OS calls its file manager, for button labels: `Explorer`.
|
||||
pub const FILE_MANAGER: &str = "Explorer";
|
||||
|
||||
/// Returns the Windows version as `major.minor.build`, e.g. `10.0.26100`, or `None` if it cannot be
|
||||
/// read. On macOS it is the product version, e.g. `26.0`.
|
||||
///
|
||||
/// This is `RtlGetVersion`, because the documented `GetVersionEx` lies to a program without a
|
||||
/// manifest saying which Windows it was made for.
|
||||
#[must_use]
|
||||
pub fn os_version() -> Option<String> {
|
||||
let mut info = OSVERSIONINFOW {
|
||||
dwOSVersionInfoSize: size_of::<OSVERSIONINFOW>() as u32,
|
||||
..Default::default()
|
||||
};
|
||||
// SAFETY: `info` is a valid, correctly sized out structure
|
||||
let status = unsafe { RtlGetVersion(&raw mut info) };
|
||||
status.is_ok().then(|| {
|
||||
format!(
|
||||
"{}.{}.{}",
|
||||
info.dwMajorVersion, info.dwMinorVersion, info.dwBuildNumber
|
||||
)
|
||||
})
|
||||
}
|
||||
|
||||
/// Shows `path` in the file manager: a folder is opened, a file is selected in its folder.
|
||||
///
|
||||
/// This starts `explorer` and does not wait for it; Explorer exits with status 1 even when it
|
||||
/// worked, so only starting it is checked, and a failure to start it is not reported. On macOS a
|
||||
/// file is opened in its default application instead of being selected.
|
||||
pub fn reveal(path: &Path) {
|
||||
let mut command = Command::new("explorer");
|
||||
if path.is_file() {
|
||||
let mut select = std::ffi::OsString::from("/select,");
|
||||
select.push(path);
|
||||
command.arg(select);
|
||||
} else {
|
||||
command.arg(path);
|
||||
}
|
||||
|
||||
// explorer exits with 1 even when it worked; only starting it matters
|
||||
let _ = command.spawn();
|
||||
}
|
||||
|
||||
/// Asks the user for a folder with the system's own dialog, and blocks until they answer.
|
||||
///
|
||||
/// Returns the folder they chose, or `None` if they canceled, the dialog could not be shown, or
|
||||
/// the path came back empty. `prompt` is the dialog's title. The dialog is made on the calling
|
||||
/// thread, which is given a COM apartment for the duration unless it already has one.
|
||||
#[must_use]
|
||||
pub fn pick_folder(prompt: &str) -> Option<PathBuf> {
|
||||
// SAFETY: COM is initialised for this thread for the duration of the dialog and released after
|
||||
// (unless some other code had initialised it differently, in which case it is theirs to release)
|
||||
unsafe {
|
||||
let initialised = CoInitializeEx(None, COINIT_APARTMENTTHREADED).is_ok();
|
||||
let chosen = pick(prompt);
|
||||
if initialised {
|
||||
CoUninitialize();
|
||||
}
|
||||
chosen
|
||||
}
|
||||
}
|
||||
|
||||
/// # Safety
|
||||
/// COM must be initialized on the calling thread.
|
||||
unsafe fn pick(prompt: &str) -> Option<PathBuf> {
|
||||
// SAFETY: the caller initialised COM; every pointer below is owned by a COM wrapper or freed
|
||||
unsafe {
|
||||
let dialog: IFileOpenDialog =
|
||||
CoCreateInstance(&FileOpenDialog, None, CLSCTX_INPROC_SERVER).ok()?;
|
||||
let options = dialog.GetOptions().ok()?;
|
||||
dialog
|
||||
.SetOptions(options | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM)
|
||||
.ok()?;
|
||||
|
||||
let title: Vec<u16> = prompt.encode_utf16().chain(Some(0)).collect();
|
||||
dialog.SetTitle(PCWSTR(title.as_ptr())).ok()?;
|
||||
|
||||
// cancelling is an error as far as COM is concerned
|
||||
dialog.Show(None).ok()?;
|
||||
|
||||
let item = dialog.GetResult().ok()?;
|
||||
let name = item.GetDisplayName(SIGDN_FILESYSPATH).ok()?;
|
||||
let path = name.to_string().ok();
|
||||
CoTaskMemFree(Some(name.0.cast_const().cast()));
|
||||
path.filter(|path| !path.is_empty()).map(PathBuf::from)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,277 @@
|
||||
//! Parsing and formatting of video timecodes: the way a position in a recording is typed on a
|
||||
//! command line and shown back.
|
||||
//!
|
||||
//! A timecode is a number of seconds of video time, an `f64`, counted from the first captured
|
||||
//! frame of a session (video `00:00.000`). A time before the first frame is negative.
|
||||
//!
|
||||
//! | Function | Does |
|
||||
//! |---|---|
|
||||
//! | [`parse`] | reads a timecode into seconds |
|
||||
//! | [`parse_span`] | reads a duration (`500ms`, `2m`) into seconds |
|
||||
//! | [`format()`] | writes seconds as a timecode |
|
||||
//!
|
||||
//! Accepted by [`parse`]: `12.5` (seconds), `12`, `00:12.500`, `1:02`, `1:02:03` and `1:02:03.25`.
|
||||
//! A leading `-` is accepted so that offsets before the start of the video can be expressed.
|
||||
//! [`format()`] writes `MM:SS.mmm`, or `H:MM:SS.mmm` from one hour on, and [`parse`] reads back
|
||||
//! what it writes.
|
||||
//!
|
||||
//! This module has no idea what a recording is: it converts between text and a number of seconds,
|
||||
//! and places nothing on a clock. Turning video seconds into a time on the master clock is the
|
||||
//! session manifest's `mach_at_video_seconds`, and the reverse its `video_seconds`.
|
||||
//!
|
||||
//! # Example
|
||||
//!
|
||||
//! ```rust
|
||||
//! use komorebi_recorder::timecode;
|
||||
//!
|
||||
//! assert_eq!(timecode::parse("00:12.500")?, 12.5);
|
||||
//! assert_eq!(timecode::parse("1:02:03")?, 3723.0);
|
||||
//! assert_eq!(timecode::parse("-1.5")?, -1.5);
|
||||
//!
|
||||
//! assert_eq!(timecode::format(12.5), "00:12.500");
|
||||
//! assert_eq!(timecode::format(3723.25), "1:02:03.250");
|
||||
//!
|
||||
//! // a span is a length of time, not a position
|
||||
//! assert_eq!(timecode::parse_span("500ms")?, 0.5);
|
||||
//! assert_eq!(timecode::parse_span("2m")?, 120.0);
|
||||
//! # Ok::<(), Box<dyn std::error::Error>>(())
|
||||
//! ```
|
||||
|
||||
use color_eyre::eyre;
|
||||
|
||||
/// Parses a timecode into seconds.
|
||||
///
|
||||
/// The forms are `[[H:]M:]S[.fraction]`, optionally preceded by `-`, with surrounding whitespace
|
||||
/// ignored: `12.5`, `12`, `00:12.500`, `1:02`, `1:02:03` and `1:02:03.25`. The hours and minutes
|
||||
/// are whole numbers, and the seconds are any non-negative number Rust reads as an `f64`. The
|
||||
/// parts are not range checked, so `1:75` is `135` seconds and `90:00` is `5400`. A `-` negates
|
||||
/// the whole timecode, and is only accepted once, at the start.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns an error if the input
|
||||
///
|
||||
/// * is empty (after trimming, and after a leading `-`): `empty timecode`;
|
||||
/// * has more than three `:`-separated parts: `expected [[H:]M:]S[.fraction]`;
|
||||
/// * has an hours or minutes part that is not an unsigned whole number (`1.5:30`, `1:-2:30`);
|
||||
/// * has a seconds part, the last one, that is not a number, or is negative, `NaN` or infinite
|
||||
/// (`abc`, `--1`, `1:-2`, `nan`, `inf`).
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::timecode::parse;
|
||||
///
|
||||
/// assert_eq!(parse("12.5")?, 12.5);
|
||||
/// assert_eq!(parse("1:02")?, 62.0);
|
||||
/// assert_eq!(parse("1:02:03.25")?, 3723.25);
|
||||
/// assert_eq!(parse("-0:01.500")?, -1.5);
|
||||
///
|
||||
/// // the parts are not range checked
|
||||
/// assert_eq!(parse("1:75")?, 135.0);
|
||||
///
|
||||
/// let error = parse("1:2:3:4").unwrap_err();
|
||||
/// assert_eq!(error.to_string(), "invalid timecode '1:2:3:4': expected [[H:]M:]S[.fraction]");
|
||||
/// assert_eq!(parse("").unwrap_err().to_string(), "empty timecode");
|
||||
/// assert!(parse("nan").is_err());
|
||||
/// # Ok::<(), Box<dyn std::error::Error>>(())
|
||||
/// ```
|
||||
pub fn parse(input: &str) -> eyre::Result<f64> {
|
||||
let trimmed = input.trim();
|
||||
let (negative, body) = match trimmed.strip_prefix('-') {
|
||||
Some(rest) => (true, rest),
|
||||
None => (false, trimmed),
|
||||
};
|
||||
|
||||
if body.is_empty() {
|
||||
eyre::bail!("empty timecode");
|
||||
}
|
||||
|
||||
let parts: Vec<&str> = body.split(':').collect();
|
||||
if parts.len() > 3 {
|
||||
eyre::bail!("invalid timecode '{input}': expected [[H:]M:]S[.fraction]");
|
||||
}
|
||||
|
||||
let mut seconds = 0.0_f64;
|
||||
for (index, part) in parts.iter().enumerate() {
|
||||
let is_last = index == parts.len() - 1;
|
||||
let invalid = || eyre::Report::msg(format!("invalid timecode '{input}'"));
|
||||
let value: f64 = if is_last {
|
||||
part.parse().map_err(|_| invalid())?
|
||||
} else {
|
||||
f64::from(part.parse::<u32>().map_err(|_| invalid())?)
|
||||
};
|
||||
|
||||
if !value.is_finite() || value < 0.0 {
|
||||
eyre::bail!("invalid timecode '{input}'");
|
||||
}
|
||||
|
||||
seconds = seconds * 60.0 + value;
|
||||
}
|
||||
|
||||
Ok(if negative { -seconds } else { seconds })
|
||||
}
|
||||
|
||||
/// Parses a duration such as `1s`, `500ms`, `1.5` (seconds) or `2m` into seconds.
|
||||
///
|
||||
/// A number followed by `ms` (milliseconds), `s` (seconds) or `m` (minutes), with nothing after it
|
||||
/// meaning seconds. Whitespace around the input, and between the number and its unit, is ignored.
|
||||
/// Hours are not a unit: use minutes, or a timecode with [`parse`].
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns an error if the number is not a number Rust reads as an `f64` (`soon`, or an empty
|
||||
/// string), or if it is negative, `NaN` or infinite: a span cannot be negative.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::timecode::parse_span;
|
||||
///
|
||||
/// assert_eq!(parse_span("1s")?, 1.0);
|
||||
/// assert_eq!(parse_span("500ms")?, 0.5);
|
||||
/// assert_eq!(parse_span("1.5")?, 1.5);
|
||||
/// assert_eq!(parse_span("2m")?, 120.0);
|
||||
///
|
||||
/// assert!(parse_span("-1s").is_err());
|
||||
/// assert!(parse_span("soon").is_err());
|
||||
/// assert_eq!(
|
||||
/// parse_span("soon").unwrap_err().to_string(),
|
||||
/// "invalid duration 'soon': expected e.g. 1s, 500ms or 1.5"
|
||||
/// );
|
||||
/// # Ok::<(), Box<dyn std::error::Error>>(())
|
||||
/// ```
|
||||
pub fn parse_span(input: &str) -> eyre::Result<f64> {
|
||||
let trimmed = input.trim();
|
||||
let (number, scale) = if let Some(rest) = trimmed.strip_suffix("ms") {
|
||||
(rest, 0.001)
|
||||
} else if let Some(rest) = trimmed.strip_suffix('s') {
|
||||
(rest, 1.0)
|
||||
} else if let Some(rest) = trimmed.strip_suffix('m') {
|
||||
(rest, 60.0)
|
||||
} else {
|
||||
(trimmed, 1.0)
|
||||
};
|
||||
|
||||
let value: f64 = number.trim().parse().map_err(|_| {
|
||||
eyre::Report::msg(format!(
|
||||
"invalid duration '{input}': expected e.g. 1s, 500ms or 1.5"
|
||||
))
|
||||
})?;
|
||||
|
||||
if !value.is_finite() || value < 0.0 {
|
||||
eyre::bail!("invalid duration '{input}': must be a non-negative number");
|
||||
}
|
||||
|
||||
Ok(value * scale)
|
||||
}
|
||||
|
||||
/// Returns `seconds` as a timecode: `MM:SS.mmm`, or `H:MM:SS.mmm` from one hour on.
|
||||
///
|
||||
/// The value is rounded to the nearest millisecond. Minutes and seconds are two digits and
|
||||
/// milliseconds three; hours have as many digits as they need. A negative value is written with a
|
||||
/// leading `-`, which a value that rounds to zero keeps (`-00:00.000`). The result is not
|
||||
/// specified for a `NaN` or infinite `seconds`.
|
||||
///
|
||||
/// [`parse`] reads back what this writes: a value that is a whole number of milliseconds comes
|
||||
/// back equal, to within floating point error (the test `format_parse_roundtrip`).
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// use komorebi_recorder::timecode::{format, parse};
|
||||
///
|
||||
/// assert_eq!(format(0.0), "00:00.000");
|
||||
/// assert_eq!(format(12.5), "00:12.500");
|
||||
/// assert_eq!(format(62.0), "01:02.000");
|
||||
/// assert_eq!(format(3723.25), "1:02:03.250");
|
||||
/// assert_eq!(format(-1.5), "-00:01.500");
|
||||
///
|
||||
/// // rounded to the millisecond
|
||||
/// assert_eq!(format(1.2346), "00:01.235");
|
||||
///
|
||||
/// assert!((parse(&format(7322.125))? - 7322.125).abs() < 1e-9);
|
||||
/// # Ok::<(), Box<dyn std::error::Error>>(())
|
||||
/// ```
|
||||
#[must_use]
|
||||
pub fn format(seconds: f64) -> String {
|
||||
let sign = if seconds < 0.0 { "-" } else { "" };
|
||||
let total_ms = (seconds.abs() * 1_000.0).round() as u64;
|
||||
let ms = total_ms % 1_000;
|
||||
let total_s = total_ms / 1_000;
|
||||
let s = total_s % 60;
|
||||
let m = (total_s / 60) % 60;
|
||||
let h = total_s / 3_600;
|
||||
|
||||
if h > 0 {
|
||||
format!("{sign}{h}:{m:02}:{s:02}.{ms:03}")
|
||||
} else {
|
||||
format!("{sign}{m:02}:{s:02}.{ms:03}")
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn close(a: f64, b: f64) -> bool {
|
||||
(a - b).abs() < 1e-9
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parses_plain_seconds() {
|
||||
assert!(close(parse("12.5").unwrap(), 12.5));
|
||||
assert!(close(parse("12").unwrap(), 12.0));
|
||||
assert!(close(parse("0.04").unwrap(), 0.04));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parses_clock_forms() {
|
||||
assert!(close(parse("00:12.500").unwrap(), 12.5));
|
||||
assert!(close(parse("1:02").unwrap(), 62.0));
|
||||
assert!(close(parse("1:02:03").unwrap(), 3723.0));
|
||||
assert!(close(parse("1:02:03.25").unwrap(), 3723.25));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parses_negative_offsets() {
|
||||
assert!(close(parse("-1.5").unwrap(), -1.5));
|
||||
assert!(close(parse("-0:01.500").unwrap(), -1.5));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn rejects_garbage() {
|
||||
for bad in [
|
||||
"", "abc", "1:2:3:4", "1.5:30", "::", "1:-2", "--1", "nan", "inf",
|
||||
] {
|
||||
assert!(parse(bad).is_err(), "{bad:?} should not parse");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parses_spans() {
|
||||
assert!(close(parse_span("1s").unwrap(), 1.0));
|
||||
assert!(close(parse_span("500ms").unwrap(), 0.5));
|
||||
assert!(close(parse_span("1.5").unwrap(), 1.5));
|
||||
assert!(close(parse_span("2m").unwrap(), 120.0));
|
||||
assert!(parse_span("-1s").is_err());
|
||||
assert!(parse_span("soon").is_err());
|
||||
assert!(parse_span("").is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn formats() {
|
||||
assert_eq!(format(12.5), "00:12.500");
|
||||
assert_eq!(format(0.0), "00:00.000");
|
||||
assert_eq!(format(62.0), "01:02.000");
|
||||
assert_eq!(format(3723.25), "1:02:03.250");
|
||||
assert_eq!(format(-1.5), "-00:01.500");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn format_parse_roundtrip() {
|
||||
for value in [0.0, 0.001, 12.5, 59.999, 3600.0, 7322.125] {
|
||||
assert!(close(parse(&format(value)).unwrap(), value));
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user