Mirrors/miller
1
0
Fork 0
mirror of https://github.com/johnkerl/miller.git synced 2026-07-17 16:38:54 +00:00
Code Issues Projects Releases Wiki Activity

docs: document time conversion thread safety (#2115)

Browse source 
Co-authored-by: John Kerl <kerl.john.r@gmail.com>
This commit is contained in:
Kral 2026-07-02 07:04:09 +08:00 • committed by GitHub
parent 9a02055670
commit 6d7c3000aa
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 34 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

35
README-dev.md
View file

@ -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