[apple/libplatform.git] / man / spinlock_deprecated.3

.Dd May 26, 2004
.Dt SPINLOCK_DEPRECATED 3
.Os Darwin
.Sh NAME
.Nm OSSpinLockTry ,
.Nm OSSpinLockLock ,
.Nm OSSpinLockUnlock
.Nd deprecated atomic spin lock synchronization primitives
.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
.Bf -symbolic
These are deprecated interfaces for userspace spinlocks, provided for
compatibility with legacy code. These interfaces should no longer be used,
particularily in situations where threads of differing priorities may contend
on the same spinlock.
.Pp
The interfaces in
.In os/lock.h
should be used instead in cases where a very low-level lock primitive is
required. In general however, using higher level synchronization primitives
such as those provided by the pthread or dispatch subsystems are preferred.
.Ef
.Pp
The OSSpinLock 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. Because it can spin, it will generally be less cpu and power efficient than
other synchronization primitives.
.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 atomic_deprecated 3
Commit	Line	Data
ada7c492 A	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