IOLocks.h Reference

Declared in
IOLocks.h

Overview

Included Headers

  • <sys/appleapiopts.h>

  • <IOKit/system.h>

  • <IOKit/IOReturn.h>

  • <IOKit/IOTypes.h>

  • <libkern/locks.h>

  • <machine/machine_routines.h>

Functions

See the Overview section above for header-level documentation.

Lock a mutex.

#ifdef IOLOCKS_INLINE
#define IOLockLock(l) lck_mtx_lock(l)
#else
void IOLockLock(
   IOLock *lock);
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the mutex. If the lock is held by any thread, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the mutex recursively from one thread will result in deadlock.

See Also

Attempt to lock a mutex.

#ifdef IOLOCKS_INLINE
#define IOLockTryLock(l) lck_mtx_try_lock(l)
#else
boolean_t IOLockTryLock(
   IOLock *lock);
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the allocated lock.

Return Value

True if the mutex was unlocked and is now locked by the caller, otherwise false.

Discussion

Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.

See Also

Unlock a mutex.

#ifdef IOLOCKS_INLINE
#define IOLockUnlock(l) lck_mtx_unlock(l)
#else
void IOLockUnlock(
   IOLock *lock);
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the allocated lock.

Discussion

Unlock the mutex and wake any blocked waiters. Results are undefined if the caller has not locked the mutex. This function may block and so should not be called from interrupt level or while a spin lock is held.

See Also

Lock a read/write lock for read.

#ifdef IOLOCKS_INLINE
#define IORWLockRead(l) lck_rw_lock_shared(l)
#else
void IORWLockRead(
   IORWLock *lock);
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the lock for read, allowing multiple readers when there are no writers. If the lock is held for write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

See Also

Unlock a read/write lock.

#ifdef IOLOCKS_INLINE
#define IORWLockUnlock(l) lck_rw_done(l)
#else
void IORWLockUnlock(
   IORWLock *lock);
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the allocated lock.

Discussion

Undo one call to IORWLockRead or IORWLockWrite. Results are undefined if the caller has not locked the lock. This function may block and so should not be called from interrupt level or while a spin lock is held.

Lock a read/write lock for write.

#ifdef IOLOCKS_INLINE
#define IORWLockWrite(l) lck_rw_lock_exclusive(l)
#else
void IORWLockWrite(
   IORWLock *lock);
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the lock for write, allowing one writer exlusive access. If the lock is held for read or write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

See Also

Lock a spin lock.

#ifdef IOLOCKS_INLINE
#define IOSimpleLockLock(l) lck_spin_lock(l)
#else
void IOSimpleLockLock(
   IOSimpleLock *lock );
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the lock.

Discussion

Lock the spin lock. If the lock is held, spin waiting for its unlock. Spin locks disable preemption, cannot be held across any blocking operation, and should be held for very short periods. When used to synchronize between interrupt context and thread context they should be locked with interrupts disabled - IOSimpleLockLockDisableInterrupt() will do both. Locking the lock recursively from one thread will result in deadlock.

Attempt to lock a spin lock.

#ifdef IOLOCKS_INLINE
#define IOSimpleLockTryLock(l) lck_spin_try_lock(l)
#else
boolean_t IOSimpleLockTryLock(
   IOSimpleLock *lock );
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the lock.

Return Value

True if the lock was unlocked and is now locked by the caller, otherwise false.

Discussion

Lock the spin lock if it is currently unlocked, and return true. If the lock is held, return false. Successful calls to IOSimpleLockTryLock should be balanced with calls to IOSimpleLockUnlock.

Unlock a spin lock.

#ifdef IOLOCKS_INLINE
#define IOSimpleLockUnlock(l) lck_spin_unlock(l)
#else
void IOSimpleLockUnlock(
   IOSimpleLock *lock );
#endif
/* !IOLOCKS_INLINE */
Parameters
lock

Pointer to the lock.

Discussion

Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.

IOLockAlloc

Allocates and initializes a mutex.

IOLock * IOLockAlloc(
   void );
Return Value

Pointer to the allocated lock, or zero on failure.

Discussion

Allocates a mutex in general purpose memory, and initializes it. Mutexes are general purpose blocking mutual exclusion locks, supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held. IOLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IOLockFree

Frees a mutex.

void IOLockFree(
   IOLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Frees a lock allocated with IOLockAlloc. Mutex should be unlocked with no waiters.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IOLockGetMachLock

Accessor to a Mach mutex.

lck_mtx_t * IOLockGetMachLock(
   IOLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Accessor to the Mach mutex.

Availability
  • Available in OS X v10.4 and later.
Declared In
IOLocks.h

IOLockLock

Lock a mutex.

void IOLockLock(
   IOLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the mutex. If the lock is held by any thread, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the mutex recursively from one thread will result in deadlock.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IOLockLock
Declared In
IOLocks.h

IOLockSleep

Sleep with mutex unlock and relock

int IOLockSleep(
   IOLock *lock,
   void *event,
   UInt32 interType);
Parameters
lock

Pointer to the locked lock.

event

The event to sleep on.

interType

How can the sleep be interrupted.

Return Value

The wait-result value indicating how the thread was awakened.

Discussion

Prepare to sleep,unlock the mutex, and re-acquire it on wakeup. Results are undefined if the caller has not locked the mutex. This function may block and so should not be called from interrupt level or while a spin lock is held.

Availability
  • Available in OS X v10.2 and later.
Declared In
IOLocks.h

IOLockTryLock

Attempt to lock a mutex.

boolean_t IOLockTryLock(
   IOLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IOLockTryLock
Declared In
IOLocks.h

IOLockUnlock

Unlock a mutex.

void IOLockUnlock(
   IOLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Unlock the mutex and wake any blocked waiters. Results are undefined if the caller has not locked the mutex. This function may block and so should not be called from interrupt level or while a spin lock is held.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IOLockUnlock
Declared In
IOLocks.h

IORecursiveLockAlloc

Allocates and initializes an recursive lock.

IORecursiveLock * IORecursiveLockAlloc(
   void );
Return Value

Pointer to the allocated lock, or zero on failure.

Discussion

Allocates a recursive lock in general purpose memory, and initializes it. Recursive locks function identically to mutexes but allow one thread to lock more than once, with balanced unlocks. IORecursiveLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORecursiveLockFree

Frees a recursive lock.

void IORecursiveLockFree(
   IORecursiveLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Frees a lock allocated with IORecursiveLockAlloc. Lock should be unlocked with no waiters.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORecursiveLockGetMachLock

Accessor to a Mach mutex.

lck_mtx_t * IORecursiveLockGetMachLock(
   IORecursiveLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Accessor to the Mach mutex.

Availability
  • Available in OS X v10.4 and later.
Declared In
IOLocks.h

IORecursiveLockHaveLock

Check if a recursive lock is held by the calling thread.

boolean_t IORecursiveLockHaveLock(
   const IORecursiveLock *lock);
Parameters
lock

Pointer to the allocated lock.

Return Value

True if the calling thread holds the lock otherwise false.

Discussion

If the lock is held by the calling thread, return true, otherwise the lock is unlocked, or held by another thread and false is returned.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORecursiveLockLock

Lock a recursive lock.

void IORecursiveLockLock(
   IORecursiveLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the recursive lock. If the lock is held by another thread, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. The lock may be taken recursively by the same thread, with a balanced number of calls to IORecursiveLockUnlock.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORecursiveLockTryLock

Attempt to lock a recursive lock.

boolean_t IORecursiveLockTryLock(
   IORecursiveLock *lock);
Parameters
lock

Pointer to the allocated lock.

Return Value

True if the lock is now locked by the caller, otherwise false.

Discussion

Lock the lock if it is currently unlocked, or held by the calling thread, and return true. If the lock is held by another thread, return false. Successful calls to IORecursiveLockTryLock should be balanced with calls to IORecursiveLockUnlock.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORecursiveLockUnlock

Unlock a recursive lock.

void IORecursiveLockUnlock(
   IORecursiveLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Undo one call to IORecursiveLockLock, if the lock is now unlocked wake any blocked waiters. Results are undefined if the caller does not balance calls to IORecursiveLockLock with IORecursiveLockUnlock. This function may block and so should not be called from interrupt level or while a spin lock is held.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORWLockAlloc

Allocates and initializes a read/write lock.

IORWLock * IORWLockAlloc(
   void );
Return Value

Pointer to the allocated lock, or zero on failure.

Discussion

Allocates and initializes a read/write lock in general purpose memory. Read/write locks provide for multiple readers, one exclusive writer, and are supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held. IORWLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORWLockFree

Frees a read/write lock.

void IORWLockFree(
   IORWLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Frees a lock allocated with IORWLockAlloc. Lock should be unlocked with no waiters.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IORWLockGetMachLock

Accessor to a Mach read/write lock.

lck_rw_t * IORWLockGetMachLock(
   IORWLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Accessor to the Mach read/write lock.

Availability
  • Available in OS X v10.4 and later.
Declared In
IOLocks.h

IORWLockRead

Lock a read/write lock for read.

void IORWLockRead(
   IORWLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the lock for read, allowing multiple readers when there are no writers. If the lock is held for write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IORWLockRead
Declared In
IOLocks.h

IORWLockUnlock

Unlock a read/write lock.

void IORWLockUnlock(
   IORWLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Undo one call to IORWLockRead or IORWLockWrite. Results are undefined if the caller has not locked the lock. This function may block and so should not be called from interrupt level or while a spin lock is held.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IORWLockUnlock
Declared In
IOLocks.h

IORWLockWrite

Lock a read/write lock for write.

void IORWLockWrite(
   IORWLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Lock the lock for write, allowing one writer exlusive access. If the lock is held for read or write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IORWLockWrite
Declared In
IOLocks.h

IOSimpleLockAlloc

Allocates and initializes a spin lock.

IOSimpleLock * IOSimpleLockAlloc(
   void );
Return Value

Pointer to the allocated lock, or zero on failure.

Discussion

Allocates and initializes a spin lock in general purpose memory. Spin locks provide non-blocking mutual exclusion for synchronization between thread context and interrupt context, or for multiprocessor synchronization, and are supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held. IOSimpleLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IOSimpleLockFree

Frees a spin lock.

void IOSimpleLockFree(
   IOSimpleLock *lock );
Parameters
lock

Pointer to the lock.

Discussion

Frees a lock allocated with IOSimpleLockAlloc.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IOSimpleLockGetMachLock

Accessor to a Mach spin lock.

lck_spin_t * IOSimpleLockGetMachLock(
   IOSimpleLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Accessor to the Mach spin lock.

Availability
  • Available in OS X v10.4 and later.
Declared In
IOLocks.h

IOSimpleLockInit

Initialize a spin lock.

void IOSimpleLockInit(
   IOSimpleLock *lock );
Parameters
lock

Pointer to the lock.

Discussion

Initialize an embedded spin lock, to the unlocked state.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IOSimpleLockLock

Lock a spin lock.

void IOSimpleLockLock(
   IOSimpleLock *lock );
Parameters
lock

Pointer to the lock.

Discussion

Lock the spin lock. If the lock is held, spin waiting for its unlock. Spin locks disable preemption, cannot be held across any blocking operation, and should be held for very short periods. When used to synchronize between interrupt context and thread context they should be locked with interrupts disabled - IOSimpleLockLockDisableInterrupt() will do both. Locking the lock recursively from one thread will result in deadlock.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IOSimpleLockLock
Declared In
IOLocks.h

IOSimpleLockLockDisableInterrupt

Lock a spin lock.

static __inline__ IOInterruptState IOSimpleLockLockDisableInterrupt(
   IOSimpleLock *lock )
Parameters
lock

Pointer to the lock.

Discussion

Lock the spin lock. If the lock is held, spin waiting for its unlock. Simple locks disable preemption, cannot be held across any blocking operation, and should be held for very short periods. When used to synchronize between interrupt context and thread context they should be locked with interrupts disabled - IOSimpleLockLockDisableInterrupt() will do both. Locking the lock recursively from one thread will result in deadlock.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

IOSimpleLockTryLock

Attempt to lock a spin lock.

boolean_t IOSimpleLockTryLock(
   IOSimpleLock *lock );
Parameters
lock

Pointer to the lock.

Discussion

Lock the spin lock if it is currently unlocked, and return true. If the lock is held, return false. Successful calls to IOSimpleLockTryLock should be balanced with calls to IOSimpleLockUnlock.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IOSimpleLockTryLock
Declared In
IOLocks.h

IOSimpleLockUnlock

Unlock a spin lock.

void IOSimpleLockUnlock(
   IOSimpleLock *lock );
Parameters
lock

Pointer to the lock.

Discussion

Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.

Availability
  • Available in OS X v10.0 and later.
See Also
  • IOSimpleLockUnlock
Declared In
IOLocks.h

IOSimpleLockUnlockEnableInterrupt

Unlock a spin lock, and restore interrupt state.

static __inline__ void IOSimpleLockUnlockEnableInterrupt(
   IOSimpleLock *lock,
   IOInterruptState state )
Parameters
lock

Pointer to the lock.

state

The interrupt state returned by IOSimpleLockLockDisableInterrupt()

Discussion

Unlock the lock, and restore preemption and interrupts to the state as they were when the lock was taken. Results are undefined if the caller has not locked the lock.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOLocks.h

Constants

See the Overview section above for header-level documentation.

IOLockLock

Constants

IOLockTryLock

Constants

IOLockUnlock

Constants

IORWLockRead

Constants

IORWLockUnlock

Constants

IORWLockWrite

Constants

IOSimpleLockLock

Constants

IOSimpleLockTryLock

Constants

IOSimpleLockUnlock

Constants

Global Variables

extern lck_grp_t *IOLockGroup;
Constants
IOLockGroup

Global lock group used by all IOKit locks. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.

Available in OS X v10.4 and later.

Declared in IOLocks.h.