OCaml Unix.localtime and ocaml-tz: thread‑safe zone conversion interoperability

Resolution: Achieving Thread-Safe Zone Conversion

To convert a POSIX timestamp to a broken-down time in an arbitrary time zone without mutating the process-level TZ variable, you must move away from Unix.localtime and Unix.gmtime. Because these functions wrap C library calls that rely on a shared static buffer and global environment state, they are inherently unsafe for concurrent use in multi-threaded OCaml applications.

The practical solution is to use a library like ocaml-tz. This library implements the IANA time zone database in pure OCaml, allowing you to pass a specific zone object as an argument to the conversion function, thereby bypassing the global C runtime state entirely.

Implementation Strategy

To implement this safely, follow these steps:

1. Avoid putenv/setenv: Do not attempt to change the TZ variable at runtime to switch zones; this creates race conditions across all threads.
2. Initialize a Zone object: Use Tz.zone "America/New_York" (or the desired identifier) to create a zone handle.
3. Perform Pure Conversion: Use the library's conversion functions that accept the zone handle and the POSIX timestamp, returning a record that does not rely on a shared static tm struct.

Analysis of Standard Library Integration

Regarding the potential for a standard library API, the following architectural assumptions apply:

• Location: A new module, such as Unix.Zone or Zonetime, would be preferable to Unix. Adding parameters to existing Unix.localtime signatures would break backward compatibility.
• Return Type: The API should return an immutable record (similar to tm but without the C-binding constraints) to ensure thread safety.
• Coexistence: The new API would coexist by ignoring the TZ environment variable entirely, relying instead on an explicit zone parameter. This separates "system local time" (legacy) from "explicit zone time" (modern).

Verification and Risks

When interoperating between Unix.localtime and ocaml-tz, be aware that discrepancies may arise if the host system's tzdata version differs from the version bundled with the OCaml library. You can verify consistency by comparing the library output against the system's zdump utility for a specific timestamp.

Missing Diagnostic: To refine this recommendation, please specify if your application must strictly adhere to the host system's tzdata updates without requiring a library re-compile.