OSUninterruptibleSpinLock_TryAcquireWithTimeout

Syntax

#include <cafe/os.h>

BOOL OSUninterruptibleSpinLock_TryAcquireWithTimeout(OSSpinLock* inSpinlock,
                                                     OSTimeNanoseconds timeout);

Parameters

inSpinlock Pointer to uninterruptible spinlock.
timeout Minimum number of nanoseconds to wait before returning FALSE.

Adhering to an exact number of nanoseconds is not guaranteed. This function only has a time-inspection granularity roughly equivalent to the processor timebase.

Return Values

Returns TRUE if the OSUninterruptibleSpinlock was acquired, or FALSE if the OSUninterruptibleSpinlock could not be acquired before the timeout.

Description

WARNING:
Threads MUST NOT mix regular OSSpinLocks with OSUninterruptibleSpinLocks.

OSUninterruptibleSpinLock_TryAcquireWithTimeout attempts to acquire an OSUninterruptibleSpinLock until the timeout time is reached. A thread may acquire an OSUninterruptibleSpinLock recursively. Upon acquiring an OSUninterruptibleSpinLock, interrupts are disabled. A thread must not leave interrupts disabled for long periods of time—typically no longer than 1-2 microseconds— to avoid disrupting user-mode COS components.

An OSUninterruptibleSpinLock is approximately 5X faster to acquire and release than a regular OSSpinLock and creates no contention for internal COS locks. The major condition is that between acquiring and releasing the OSUninterruptibleSpinLock, interrupts are disabled and must remain disabled until the corresponding OSUninterruptibleSpinLock_Release is called.

OSUninterruptibleSpinLock_Acquire and OSUninterruptibleSpinLock_Release purposely have the same parameter lists and same-sized data structures as the OSSpinLock Acquire and Release functions. This is so that OSUninterruptibleSpinLock can serve as a drop-in replacement for regular OSSpinLock in many situations.

OSUninterruptibleSpinLocks do not participate in the thread canceling mechanism. If a thread wishes to benefit from both the faster OSUninterruptibleSpinLock and from the ability to cross-thread cancel a thread, OSTestThreadCancel should be called before OSUninterruptibleSpinLock_AcquireWithTimeout and after OSUninterruptibleSpinLock_Release.

Do Not Call From

None.

See Also

OSInitSpinLock
OSAcquireSpinLock
OSReleaseSpinLock
OSTryAcquireSpinLock
OSUninterruptibleSpinLock_Acquire
OSUninterruptibleSpinLock_Release
OSUninterruptibleSpinLock_TryAcquire
OSDisableInterrupts
OSEnableInterrupts
OSRestoreInterrupts
OSIsInterruptEnabled

Revision History

2013/05/08 Automated cleanup pass.
2012/08/01 Cleanup Pass.
2011/04/21 Initial version.


CONFIDENTIAL