[apple/libc.git] / sys / spinlock.3

.Dd May 26, 2004
.Dt SPINLOCK 3
.Os Darwin
.Sh NAME
.Nm OSSpinLockTry ,
.Nm OSSpinLockLock ,
.Nm OSSpinLockUnlock
.Nd atomic spin lock synchronization primitives
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In libkern/OSAtomic.h
.Ft bool
.Fn OSSpinLockTry "OSSpinLock *lock"
.Ft void
.Fn OSSpinLockLock "OSSpinLock *lock"
.Ft void
.Fn OSSpinLockUnlock "OSSpinLock *lock"
.Sh DESCRIPTION
Spin locks are a simple, fast, thread-safe synchronization primitive that is
suitable in situations where contention is expected to be low.  The spinlock
operations use memory barriers to synchronize access to shared memory protected
by the lock.  Preemption is possible while the lock is held.
.Pp
.Ft OSSpinLock
is an integer type.  The convention is that unlocked is zero, and locked is nonzero.
Locks must be naturally aligned and cannot be in cache-inhibited memory.
.Pp
.Fn OSSpinLockLock
will spin if the lock is already held, but employs various strategies to back off,
making it immune to most priority-inversion livelocks.  But because it can spin, it
may be inefficient in some situations.
.Pp
.Fn OSSpinLockTry
immediately returns false if the lock was held, true if it took the lock.
It does not spin.
.Pp
.Fn OSSpinLockUnlock
unconditionally unlocks the lock by zeroing it.
.Sh RETURN VALUES
.Fn OSSpinLockTry
returns true if it took the lock, false if the lock was already held.
.Sh SEE ALSO
.Xr atomic 3 ,
.Xr atomicqueue 3 ,
.Xr barrier 3
Commit	Line	Data
59e0d9fe A	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