From 6d7c3000aab55a80c3e1099385a7d819e11b43a2 Mon Sep 17 00:00:00 2001 From: Kral <118106297+dashitongzhi@users.noreply.github.com> Date: Thu, 2 Jul 2026 07:04:09 +0800 Subject: [PATCH] docs: document time conversion thread safety (#2115) Co-authored-by: John Kerl --- README-dev.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/README-dev.md b/README-dev.md index e09a49ae9..610f3e78c 100644 --- a/README-dev.md +++ b/README-dev.md @@ -22,7 +22,40 @@ The Go implementation is auto-built using GitHub Actions: see [.github/workflows * The quoted-DKVP feature from [issue 266](https://github.com/johnkerl/miller/issues/266) will be easily addressed. * String/number-formatting issues in [issue 211](https://github.com/johnkerl/miller/issues/211), [issue 178](https://github.com/johnkerl/miller/issues/178), [issue 151](https://github.com/johnkerl/miller/issues/151), and [issue 259](https://github.com/johnkerl/miller/issues/259) will be fixed during the Go port. * I think some DST/timezone issues such as [issue 359](https://github.com/johnkerl/miller/issues/359) will be easier to fix using the Go datetime library than using the C datetime library -* The code will be easier to read and, I hope, easier for others to contribute to. What this means is it should be quicker and easier to add new features to Miller -- after the development-time cost of the port itself is paid, of course. +* The code will be easier to read, and, I hope, easier for others to contribute to. What this means is it should be quicker and easier to add new features to Miller -- after the development-time cost of the port itself is paid, of course. + +## Developer note: C time conversion and thread safety + +This note is for developers who are looking at old Miller 5 C code, +release branches, downstream forks, or references to `mlr_timegm`/`timegm` +while working on [issue 1816](https://github.com/johnkerl/miller/issues/1816). +Current Miller is implemented in Go, so normal work on `main` should prefer +Go's `time` package and should not reintroduce C-library time-conversion +wrappers. + +When maintaining legacy C code, treat UTC/local timestamp conversion as a +thread-safety boundary. Some historical implementations of `timegm` are +small portability wrappers around `mktime`: they temporarily change the +process-wide `TZ` environment variable, call `tzset`, run the conversion, and +then restore the previous environment. That pattern can be acceptable in a +single-threaded command-line path, but it is not safe to call concurrently +because the environment and timezone state are global to the process. + +If a legacy `mlr_timegm` helper is needed, document whether it is merely a +portable `timegm` replacement or whether it mutates `TZ`. Do not call such a +helper from multiple worker threads unless access is serialized and all callers +understand that unrelated local-time formatting/parsing in the same process may +observe the temporary timezone. Prefer a platform `timegm`/`_mkgmtime`-style +function that does not rely on changing global process state, or an explicit +UTC conversion algorithm, when portability permits. + +For new code, keep timezone selection explicit in function arguments or in the +existing CLI configuration rather than by changing process environment during a +conversion. If tests are added around legacy C conversion behavior, include a +comment noting whether they assume single-threaded execution. This keeps the +Go implementation's concurrency model separate from the older C portability +tradeoffs and gives future maintainers a clear warning before touching +`mlr_timegm` or related `timegm` compatibility code. # Why Go