IOLocks.h

Includes:
<sys/appleapiopts.h>
<IOKit/system.h>
<IOKit/IOReturn.h>
<IOKit/IOTypes.h>
<libkern/locks.h>
<machine/machine_routines.h>

Overview

Use the links in the table of contents to the left to access the documentation.


Functions

IOLockAlloc

Allocates and initializes a mutex.

IOLockFree

Frees a mutex.

IOLockGetMachLock

Accessor to a Mach mutex.

IOLockLock_multideclaration_block

Lock a mutex.

IOLockSleep

Sleep with mutex unlock and relock

IOLockTryLock_multideclaration_block

Attempt to lock a mutex.

lck_mtx_lock

Lock a mutex.

lck_mtx_try_lock

Attempt to lock a mutex.

lck_mtx_unlock

Sleep with mutex unlock and relock

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.

IOLockFree

Frees a mutex. 

void IOLockFree(
    IOLock *lock);
Parameters
lock

Pointer to the allocated lock.

Discussion

Frees a lock allocated with IOLockAlloc. Any blocked waiters will not be woken.

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.

IOLockLock_multideclaration_block

Lock a mutex.

See Also:

IOLockLock

void lck_mtx_lock(
    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.

IOLockSleep

Sleep with mutex unlock and relock

See Also:

IOLockUnlock

void lck_mtx_unlock(
    IOLock *lock) __DARWIN10_ALIAS(
    lck_mtx_unlock(
        IOLock * lock); #endif 
    /* __i386__ */
    #endif 
    /* !IOLOCKS_INLINE */ 
    int IOLockSleep(
        IOLock * lock,
        void *event,
        UInt32 interType);  int IOLockSleepDeadline(
        IOLock * lock,
        void *event, 
        AbsoluteTime deadline,
        UInt32 interType);  void IOLockWakeup(
        IOLock * lock,
        void *event,
        bool oneThread);  #ifdef __APPLE_API_OBSOLETE  
    /* The following API is deprecated */
    typedef enum
Parameters
lock

Pointer to the allocated lock.

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.

IOLockTryLock_multideclaration_block

Attempt to lock a mutex.

See Also:

IOLockTryLock

boolean_t lck_mtx_try_lock(
    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.

lck_mtx_lock

Lock a mutex.

See Also:

IOLockLock

void lck_mtx_lock(
    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.

lck_mtx_try_lock

Attempt to lock a mutex.

See Also:

IOLockTryLock

boolean_t lck_mtx_try_lock(
    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.

lck_mtx_unlock

Sleep with mutex unlock and relock

See Also:

IOLockUnlock

void lck_mtx_unlock(
    IOLock *lock) __DARWIN10_ALIAS(
    lck_mtx_unlock(
        IOLock * lock); #endif 
    /* __i386__ */
    #endif 
    /* !IOLOCKS_INLINE */ 
    int IOLockSleep(
        IOLock * lock,
        void *event,
        UInt32 interType);  int IOLockSleepDeadline(
        IOLock * lock,
        void *event, 
        AbsoluteTime deadline,
        UInt32 interType);  void IOLockWakeup(
        IOLock * lock,
        void *event,
        bool oneThread);  #ifdef __APPLE_API_OBSOLETE  
    /* The following API is deprecated */
    typedef enum
Parameters
lock

Pointer to the allocated lock.

lock

Pointer to the locked lock.

event

The event to sleep on.

interType

How can the sleep be interrupted.

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.

Globals

IOLockGroup

IOLockGroup

extern lck_grp_t *IOLockGroup;
Discussion

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.

Macro Definitions

IOLockLock

Lock a mutex.

IOLockTryLock

Attempt to lock a mutex.

IOLockUnlock

Sleep with mutex unlock and relock

IOLockLock

Lock a mutex.

See Also:

IOLockLock_multideclaration_block

lck_mtx_lock

#ifdef IOLOCKS_INLINE 
#define IOLockLock(l) lck_mtx_lock(l) 
#else 
void lck_mtx_lock(
    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.

IOLockTryLock

Attempt to lock a mutex.

See Also:

IOLockTryLock_multideclaration_block

lck_mtx_try_lock

#ifdef IOLOCKS_INLINE 
#define IOLockTryLock(l) lck_mtx_try_lock(l) 
#else 
boolean_t lck_mtx_try_lock(
    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.

IOLockUnlock

Sleep with mutex unlock and relock

See Also:

IOLockUnlock_multideclaration_block

lck_mtx_unlock

#ifdef IOLOCKS_INLINE 
#define IOLockUnlock(l) lck_mtx_unlock(l) 
#else 
#if defined(__i386__) 
void lck_mtx_unlock(
    IOLock *lock) __DARWIN10_ALIAS(
    lck_mtx_unlock(
        IOLock * lock); #endif 
    /* __i386__ */
    #endif 
    /* !IOLOCKS_INLINE */ 
    int IOLockSleep(
        IOLock * lock,
        void *event,
        UInt32 interType);  int IOLockSleepDeadline(
        IOLock * lock,
        void *event, 
        AbsoluteTime deadline,
        UInt32 interType);  void IOLockWakeup(
        IOLock * lock,
        void *event,
        bool oneThread);  #ifdef __APPLE_API_OBSOLETE  
    /* The following API is deprecated */
    typedef enum       
#endif
Included Defines
IOLockSleep

Parameters
lock

Pointer to the allocated lock.

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.

 

 

Last Updated: 2009-10-14