man/spinlock_deprecated.3

   1 .Dd May 26, 2004
   2 .Dt SPINLOCK_DEPRECATED 3
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm OSSpinLockTry ,
   6 .Nm OSSpinLockLock ,
   7 .Nm OSSpinLockUnlock
   8 .Nd deprecated atomic spin lock synchronization primitives
   9 .Sh SYNOPSIS
  10 .In libkern/OSAtomic.h
  11 .Ft bool
  12 .Fn OSSpinLockTry "OSSpinLock *lock"
  13 .Ft void
  14 .Fn OSSpinLockLock "OSSpinLock *lock"
  15 .Ft void
  16 .Fn OSSpinLockUnlock "OSSpinLock *lock"
  17 .Sh DESCRIPTION
  18 .Bf -symbolic
  19 These are deprecated interfaces for userspace spinlocks, provided for
  20 compatibility with legacy code. These interfaces should no longer be used,
  21 particularily in situations where threads of differing priorities may contend
  22 on the same spinlock.
  23 .Pp
  24 The interfaces in
  25 .In os/lock.h
  26 should be used instead in cases where a very low-level lock primitive is
  27 required. In general however, using higher level synchronization primitives
  28 such as those provided by the pthread or dispatch subsystems are preferred.
  29 .Ef
  30 .Pp
  31 The OSSpinLock operations use memory barriers to synchronize access to shared
  32 memory protected by the lock.  Preemption is possible while the lock is held.
  33 .Pp
  34 .Ft OSSpinLock
  35 is an integer type.  The convention is that unlocked is zero, and locked is nonzero.
  36 Locks must be naturally aligned and cannot be in cache-inhibited memory.
  37 .Pp
  38 .Fn OSSpinLockLock
  39 will spin if the lock is already held, but employs various strategies to back
  40 off. Because it can spin, it will generally be less cpu and power efficient than
  41 other synchronization primitives.
  42 .Pp
  43 .Fn OSSpinLockTry
  44 immediately returns false if the lock was held, true if it took the lock.
  45 It does not spin.
  46 .Pp
  47 .Fn OSSpinLockUnlock
  48 unconditionally unlocks the lock by zeroing it.
  49 .Sh RETURN VALUES
  50 .Fn OSSpinLockTry
  51 returns true if it took the lock, false if the lock was already held.
  52 .Sh SEE ALSO
  53 .Xr atomic 3 ,
  54 .Xr atomic_deprecated 3