OSAcquireSpinLock

Syntax

#include <cafe/os.h>

BOOL OSAcquireSpinLock(OSSpinLock* spinlock);

Parameters

spinlock Pointer to spinlock.

Return Values

Returns TRUE if the OSSpinLock was acquired, or FALSE otherwise.

Description

OSAcquireSpinLock busy-waits to acquire an OSSpinLock if the spinlock has never been acquired.

Important usage notes while holding a spinlock:

OSSpinlock is designed to handle thread priority inversion issues. Boosting the current thread to highest-priority while holding an OSSpinLock prevents priority-inversion issues. Boosting and deboosting takes time and slightly reduces the performance of OSSpinLock.

The OSSpinLock implementation works by boosting the priority of the current thread to the highest in the system when any OSSpinLock is held. Because of this, other threads do not run until the current thread explicitly yields (sleeps) or until the current thread releases the OSSpinLock. If a thread wants to sleep, use an OSMutex.

Do not continue holding OSSpinLock when a process switch happens. To process switch, call OSReleaseForeground. A large amount of OS work happens during that call, which requires switching threads and coordinating with many of the user-mode drivers on multiple cores. Holding a spinlock across that time places a thread in a higher priority while the lock is held, and could affect the actions of system threads.

OSSpinLock is not a "pure" spinlock implementation. A "pure" spinlock implementation may suffer from priority inversion if a system callback that attempted to acquire a lock is executed while a lower-priority thread holds the same lock.

Do Not Call From

Callbacks Do not call this function from any callback function.

See Also

OSInitSpinLock
OSReleaseSpinLock
OSTryAcquireSpinLock
OSTryAcquireSpinLockWithTimeout

Revision History

2013/05/08 Automated cleanup pass.
2012/08/01 Cleanup Pass.
2010/08/23 Initial version.


CONFIDENTIAL