Mac Developer Library

Developer

IOLocks.h Reference

Options
Deployment Target:

On This Page

IOLocks.h Reference

Included Headers

  • <sys/appleapiopts.h>

  • <IOKit/system.h>

  • <IOKit/IOReturn.h>

  • <IOKit/IOTypes.h>

  • <libkern/locks.h>

  • <machine/machine_routines.h>

Functions

  • Lock a mutex.

    Declaration

    Objective-C

    #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.

    Import Statement

    See Also

    IOLockLock

  • Attempt to lock a mutex.

    Declaration

    Objective-C

    #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.

    Import Statement

    See Also

    IOLockTryLock

  • Unlock a mutex.

    Declaration

    Objective-C

    #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.

    Import Statement

    See Also

    IOLockUnlock

  • Lock a read/write lock for read.

    Declaration

    Objective-C

    #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.

    Import Statement

    See Also

    IORWLockRead

  • Unlock a read/write lock.

    Declaration

    Objective-C

    #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.

    Import Statement

    See Also

    IORWLockUnlock

  • Lock a read/write lock for write.

    Declaration

    Objective-C

    #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.

    Import Statement

    See Also

    IORWLockWrite

  • Lock a spin lock.

    Declaration

    Objective-C

    #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.

    Import Statement

    See Also

    IOSimpleLockLock

  • Attempt to lock a spin lock.

    Declaration

    Objective-C

    #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.

    Import Statement

  • Unlock a spin lock.

    Declaration

    Objective-C

    #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.

    Import Statement

  • Allocates and initializes a mutex.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Frees a mutex.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Accessor to a Mach mutex.

    Declaration

    Objective-C

    lck_mtx_t * IOLockGetMachLock ( IOLock *lock );

    Parameters

    lock

    Pointer to the allocated lock.

    Discussion

    Accessor to the Mach mutex.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Lock a mutex.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IOLockLock

  • Sleep with mutex unlock and relock

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.2 and later.

  • Attempt to lock a mutex.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IOLockTryLock

  • Unlock a mutex.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IOLockUnlock

  • Allocates and initializes an recursive lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Frees a recursive lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Accessor to a Mach mutex.

    Declaration

    Objective-C

    lck_mtx_t * IORecursiveLockGetMachLock ( IORecursiveLock *lock );

    Parameters

    lock

    Pointer to the allocated lock.

    Discussion

    Accessor to the Mach mutex.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Lock a recursive lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Attempt to lock a recursive lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Unlock a recursive lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Allocates and initializes a read/write lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Frees a read/write lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Accessor to a Mach read/write lock.

    Declaration

    Objective-C

    lck_rw_t * IORWLockGetMachLock ( IORWLock *lock );

    Parameters

    lock

    Pointer to the allocated lock.

    Discussion

    Accessor to the Mach read/write lock.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Lock a read/write lock for read.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IORWLockRead

  • Unlock a read/write lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IORWLockUnlock

  • Lock a read/write lock for write.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IORWLockWrite

  • Allocates and initializes a spin lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Frees a spin lock.

    Declaration

    Objective-C

    void IOSimpleLockFree ( IOSimpleLock *lock );

    Parameters

    lock

    Pointer to the lock.

    Discussion

    Frees a lock allocated with IOSimpleLockAlloc.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Accessor to a Mach spin lock.

    Declaration

    Objective-C

    lck_spin_t * IOSimpleLockGetMachLock ( IOSimpleLock *lock );

    Parameters

    lock

    Pointer to the allocated lock.

    Discussion

    Accessor to the Mach spin lock.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Initialize a spin lock.

    Declaration

    Objective-C

    void IOSimpleLockInit ( IOSimpleLock *lock );

    Parameters

    lock

    Pointer to the lock.

    Discussion

    Initialize an embedded spin lock, to the unlocked state.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Lock a spin lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IOSimpleLockLock

  • Lock a spin lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Attempt to lock a spin lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IOSimpleLockTryLock

  • Unlock a spin lock.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    IOSimpleLockUnlock

  • Unlock a spin lock, and restore interrupt state.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    Constants

    Import Statement

  • Declaration

    Objective-C

    extern lck_grp_t *IOLockGroup;

    Constants

    • IOLockGroup

      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.

    Import Statement