From cfe7f21dd55fca8250c34bae8837d241f4a9876e Mon Sep 17 00:00:00 2001 From: Joe Tsai Date: Tue, 13 Feb 2024 15:34:26 -0800 Subject: [PATCH] log/slog: document atomicity guarantees and ordering limitations of handlers The new wording is slightly more strict than before in that it guarantees each Write only contains exactly one Record, while the previous wording opened up the possibility for multiple Records in a Write call. We also add a comment about the lack of sorting guarantees for concurrently logged Records. That is, the obtained lock only covers the Write call, rather than the combination of the call to time.Now, JSON/text serialization, and also the Write call. Change-Id: Ia65c50579215a35a1f5b2952c6954ddb60e7fe66 Reviewed-on: https://go-review.googlesource.com/c/go/+/563976 Reviewed-by: Jonathan Amsterdam TryBot-Bypass: Jonathan Amsterdam Reviewed-by: Alan Donovan --- src/log/slog/doc.go | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/log/slog/doc.go b/src/log/slog/doc.go index 001559326b..cc034ca4b9 100644 --- a/src/log/slog/doc.go +++ b/src/log/slog/doc.go @@ -310,8 +310,10 @@ Then use a value of that type in log calls: Now computeExpensiveValue will only be called when the line is enabled. The built-in handlers acquire a lock before calling [io.Writer.Write] -to ensure that each record is written in one piece. User-defined -handlers are responsible for their own locking. +to ensure that exactly one [Record] is written at a time in its entirety. +Although each log record has a timestamp, +the built-in handlers do not use that time to sort the written records. +User-defined handlers are responsible for their own locking and sorting. # Writing a handler -- 2.48.1