sys/spinlock.3

   1 .Dd May 26, 2004
   2 .Dt SPINLOCK 3
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm OSSpinLockTry ,
   6 .Nm OSSpinLockLock ,
   7 .Nm OSSpinLockUnlock
   8 .Nd atomic spin lock synchronization primitives
   9 .Sh LIBRARY
  10 .Lb libc
  11 .Sh SYNOPSIS
  12 .In libkern/OSAtomic.h
  13 .Ft bool
  14 .Fn OSSpinLockTry "OSSpinLock *lock"
  15 .Ft void
  16 .Fn OSSpinLockLock "OSSpinLock *lock"
  17 .Ft void
  18 .Fn OSSpinLockUnlock "OSSpinLock *lock"
  19 .Sh DESCRIPTION
  20 Spin locks are a simple, fast, thread-safe synchronization primitive that is
  21 suitable in situations where contention is expected to be low.  The spinlock
  22 operations use memory barriers to synchronize access to shared memory protected
  23 by the lock.  Preemption is possible while the lock is held.
  24 .Pp
  25 .Ft OSSpinLock
  26 is an integer type.  The convention is that unlocked is zero, and locked is nonzero.
  27 Locks must be naturally aligned and cannot be in cache-inhibited memory.
  28 .Pp
  29 .Fn OSSpinLockLock
  30 will spin if the lock is already held, but employs various strategies to back off,
  31 making it immune to most priority-inversion livelocks.  But because it can spin, it
  32 may be inefficient in some situations.
  33 .Pp
  34 .Fn OSSpinLockTry
  35 immediately returns false if the lock was held, true if it took the lock.
  36 It does not spin.
  37 .Pp
  38 .Fn OSSpinLockUnlock
  39 unconditionally unlocks the lock by zeroing it.
  40 .Sh RETURN VALUES
  41 .Fn OSSpinLockTry
  42 returns true if it took the lock, false if the lock was already held.
  43 .Sh SEE ALSO
  44 .Xr atomic 3 ,
  45 .Xr atomicqueue 3 ,
  46 .Xr barrier 3