Functions



IOLockAlloc

Abstract: Allocates and initializes an osfmk mutex.
IOLock * IOLockAlloc( void );

Allocates an osfmk mutex in general purpose memory, and initilizes it. Mutexes are general purpose blocking mutual exclusion locks, supplied by osfmk/kern/lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.

Result: Pointer to the allocated lock, or zero on failure.

IOLockFree

Abstract: Frees an osfmk mutex.
void IOLockFree( IOLock * lock);

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

Parameters

NameDescription
lockPointer to the allocated lock.

IOLockLock

Abstract: Lock an osfmk mutex.
static __inline__ void IOLockLock( IOLock * lock)
{
 _mutex_lock(lock);

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 simple lock is held. Locking the mutex recursively from one thread will result in deadlock.

Parameters

NameDescription
lockPointer to the allocated lock.

IOLockTryLock

Abstract: Attempt to lock an osfmk mutex.
static __inline__ boolean_t IOLockTryLock( IOLock * lock)
{
 return(_mutex_try(lock));

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

Parameters

NameDescription
lockPointer to the allocated lock.
Result: True if the mutex was unlocked and is now locked by the caller, otherwise false.

IOLockUnlock

Abstract: Unlock an osfmk mutex.
static __inline__ void IOLockUnlock( IOLock * lock)
{
 mutex_unlock(lock);

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 simple lock is held.

Parameters

NameDescription
lockPointer to the allocated lock.

IORWLockAlloc

Abstract: Allocates and initializes an osfmk general (read/write) lock.
IORWLock * IORWLockAlloc( void );

Allocates an initializes an osfmk lock_t in general purpose memory, and initilizes it. Read/write locks provide for multiple readers, one exclusive writer, and are supplied by osfmk/kern/lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.

Result: Pointer to the allocated lock, or zero on failure.

IORWLockFree

Abstract: Frees an osfmk general (read/write) lock.
void IORWLockFree( IORWLock * lock);

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

Parameters

NameDescription
lockPointer to the allocated lock.

IORWLockRead

Abstract: Lock an osfmk lock for read.
static __inline__ void IORWLockRead( IORWLock * lock)
{
 lock_read( lock);

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 simple lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

Parameters

NameDescription
lockPointer to the allocated lock.

IORWLockUnlock

Abstract: Unlock an osfmk lock.
static __inline__ void IORWLockUnlock( IORWLock * lock)
{
 lock_done( lock);

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 simple lock is held.

Parameters

NameDescription
lockPointer to the allocated lock.

IORWLockWrite

Abstract: Lock an osfmk lock for write.
static __inline__ void IORWLockWrite( IORWLock * lock)
{
 lock_write( lock);

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 simple lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

Parameters

NameDescription
lockPointer to the allocated lock.

IORecursiveLockAlloc

Abstract: Allocates and initializes an recursive lock.
IORecursiveLock * IORecursiveLockAlloc( void );

Allocates a recursive lock in general purpose memory, and initilizes it. Recursive locks function identically to osfmk mutexes but allow one thread to lock more than once, with balanced unlocks.

Result: Pointer to the allocated lock, or zero on failure.

IORecursiveLockFree

Abstract: Frees a recursive lock.
void IORecursiveLockFree( IORecursiveLock * lock);

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

Parameters

NameDescription
lockPointer to the allocated lock.

IORecursiveLockHaveLock

Abstract: Check if a recursive lock is held by the calling thread.
boolean_t IORecursiveLockHaveLock( const IORecursiveLock * lock);

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.

Parameters

NameDescription
lockPointer to the allocated lock.
Result: True if the calling thread holds the lock otherwise false.

IORecursiveLockLock

Abstract: Lock a recursive lock.
void IORecursiveLockLock( IORecursiveLock * lock);

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 simple lock is held. The lock may be taken recursively by the same thread, with a balanced number of calls to IORecursiveLockUnlock.

Parameters

NameDescription
lockPointer to the allocated lock.

IORecursiveLockTryLock

Abstract: Attempt to lock a recursive lock.
boolean_t IORecursiveLockTryLock( IORecursiveLock * lock);

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.

Parameters

NameDescription
lockPointer to the allocated lock.
Result: True if the lock is now locked by the caller, otherwise false.

IORecursiveLockUnlock

Abstract: Unlock a recursive lock.
void IORecursiveLockUnlock( IORecursiveLock * lock);

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 simple lock is held.

Parameters

NameDescription
lockPointer to the allocated lock.

IOSimpleLockAlloc

Abstract: Allocates and initializes an osfmk simple (spin) lock.
IOSimpleLock * IOSimpleLockAlloc( void );

Allocates an initializes an osfmk simple lock in general purpose memory, and initilizes it. Simple locks provide non-blocking mutual exclusion for synchronization between thread context and interrupt context, or for multiprocessor synchronization, and are supplied by osfmk/kern/simple_lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.

Result: Pointer to the allocated lock, or zero on failure.

IOSimpleLockFree

Abstract: Frees an osfmk simple (spin) lock.
void IOSimpleLockFree( IOSimpleLock * lock );

Frees a lock allocated with IOSimpleLockAlloc.

Parameters

NameDescription
lockPointer to the lock.

IOSimpleLockInit

Abstract: Initialize an osfmk simple (spin) lock.
void IOSimpleLockInit( IOSimpleLock * lock );

Initialize an embedded osfmk simple lock, to the unlocked state.

Parameters

NameDescription
lockPointer to the lock.

IOSimpleLockLock

Abstract: Lock an osfmk simple lock.
static __inline__ void IOSimpleLockLock( IOSimpleLock * lock )
{
 simple_lock( lock );

Lock the simple 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.

Parameters

NameDescription
lockPointer to the lock.

IOSimpleLockLockDisableInterrupt

Abstract: Lock an osfmk simple lock.
static __inline__ IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
{
 IOInterruptState state = ml_set_interrupts_enabled( false );

Lock the simple 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.

Parameters

NameDescription
lockPointer to the lock.

IOSimpleLockTryLock

Abstract: Attempt to lock an osfmk simple lock.
static __inline__ boolean_t IOSimpleLockTryLock( IOSimpleLock * lock )
{
 return( simple_lock_try( lock ) );

Lock the simple 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.

Parameters

NameDescription
lockPointer to the lock.
Result: True if the lock was unlocked and is now locked by the caller, otherwise false.

IOSimpleLockUnlock

Abstract: Unlock an osfmk simple lock.
static __inline__ void IOSimpleLockUnlock( IOSimpleLock * lock )
{
 simple_unlock( lock );

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

Parameters

NameDescription
lockPointer to the lock.

IOSimpleLockUnlockEnableInterrupt

Abstract: Unlock an osfmk simple lock, and restore interrupt state.
static __inline__ void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
 IOInterruptState state )
{
 simple_unlock( lock );

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.

Parameters

NameDescription
lockPointer to the lock.
stateThe interrupt state returned by IOSimpleLockLockDisableInterrupt()

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)