From 944712dad749f39d087b868d8e5c2126601994f9 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@well-typed.com>
Date: Tue, 7 Jan 2025 15:04:57 +0000
Subject: [PATCH] base: Update description of locking behavior

---
 .../ghc-internal/src/GHC/Internal/IO/Handle/Lock.hs  | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/libraries/ghc-internal/src/GHC/Internal/IO/Handle/Lock.hs b/libraries/ghc-internal/src/GHC/Internal/IO/Handle/Lock.hs
index ce7d32c881a..63a0758970d 100644
--- a/libraries/ghc-internal/src/GHC/Internal/IO/Handle/Lock.hs
+++ b/libraries/ghc-internal/src/GHC/Internal/IO/Handle/Lock.hs
@@ -35,14 +35,20 @@ import GHC.Internal.IO.Handle.Lock.NoOp
 --
 -- Things to be aware of:
 --
--- 1) This function may block inside a C call. If it does, in order to be able
+-- 1. This function may block inside a C call. If it does, in order to be able
 -- to interrupt it with asynchronous exceptions and/or for other threads to
 -- continue working, you MUST use threaded version of the runtime system.
 --
--- 2) The implementation uses 'LockFileEx' on Windows and 'flock' otherwise,
+-- 2. The implementation uses relies on any of a number of locking
+-- facilities, depending upon what the platform supports:
+--
+--   * 'LockFileEx' is used on Windows
+--   * On platforms that support it we use the @F_OFD_SETLK@ and @F_OFD_SETLKW@ @fnctl@s.
+--   * Otherwise we use @flock@
+--
 -- hence all of their caveats also apply here.
 --
--- 3) On non-Windows platforms that don't support 'flock' (e.g. Solaris) this
+-- 3. On non-Windows platforms that don't support 'flock' (e.g. Solaris) this
 -- function throws 'FileLockingNotImplemented'. We deliberately choose to not
 -- provide fcntl based locking instead because of its broken semantics.
 --
-- 
GitLab