locking.9: warn about using sleepable lock address as a sleep channel

(cherry picked from commit 56bc43f5d02bd0745d597db44c285bf78d083762)

1 files changed, 10 insertions, 5 deletions

diff --git a/share/man/man9/locking.9 b/share/man/man9/locking.9
index ad044b6e1d46..9afdcd56f4f6 100644
--- a/share/man/man9/locking.9
+++ b/share/man/man9/locking.9
@@ -205,11 +205,6 @@ The functions
 and
 .Fn wakeup_one
 also handle event-based thread blocking.
-Unlike condition variables,
-arbitrary addresses may be used as wait channels and a dedicated
-structure does not need to be allocated.
-However, care must be taken to ensure that wait channel addresses are
-unique to an event.
 If a thread must wait for an external event, it is put to sleep by
 .Fn tsleep ,
 .Fn msleep ,
@@ -222,6 +217,16 @@ Threads may also wait using one of the locking primitive sleep routines
 or
 .Xr sx_sleep 9 .
 .Pp
+Unlike condition variables,
+arbitrary addresses may be used as wait channels and a dedicated
+structure does not need to be allocated.
+However, care must be taken to ensure that wait channel addresses are
+unique to an event.
+For example, the memory address of a sleepable lock such as a
+.Xr sx 9
+must not be used as a sleep channel, because the lock implementation
+will internally use the same address as a wait channel.
+.Pp
 The parameter
 .Fa chan
 is an arbitrary address that uniquely identifies the event on which