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 <jba@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>

diff --git a/src/log/slog/doc.go b/src/log/slog/doc.go
index 001559326b3eea36ff56beacf58dc1ff23f2ef50..cc034ca4b97635f800c9b02783f955f6246ade5f 100644 (file)
--- 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