xnu-7195.50.7.100.1.tar.gz

[apple/xnu.git] / iokit / IOKit / IOLocks.h

diff --git a/iokit/IOKit/IOLocks.h b/iokit/IOKit/IOLocks.h
index 2c89a177aec40c15939b24316dc35e30c949fef4..c585840f049f5186fdd0b591d4046e090e928746 100644 (file)
--- a/iokit/IOKit/IOLocks.h
+++ b/iokit/IOKit/IOLocks.h
@@ -298,6 +298,17 @@ lck_rw_t * IORWLockGetMachLock( IORWLock * lock);
 void    IORWLockRead(IORWLock * lock);
 #endif  /* !IOLOCKS_INLINE */
 
 void    IORWLockRead(IORWLock * lock);
 #endif  /* !IOLOCKS_INLINE */
 

+/*! @function IORWLockTryRead
+ *   @abstract Attempt to lock a read/write lock for read.
+ *  @discussion Lock the lock for read, allowing multiple readers when there are no writers. If the lock is held for write, return false. Return true otherwise.
+ *   @param lock Pointer to the allocated lock. */
+
+#ifdef  IOLOCKS_INLINE
+#define IORWLockTryRead(l)        lck_rw_try_lock_shared(l)
+#else
+void    IORWLockTryRead( IORWLock * lock);
+#endif  /* !IOLOCKS_INLINE */
+

 /*! @function IORWLockWrite
  *   @abstract Lock a read/write lock for write.
  *   @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.
 /*! @function IORWLockWrite
  *   @abstract Lock a read/write lock for write.
  *   @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.


@@ -309,6 +320,17 @@ void    IORWLockRead(IORWLock * lock);
 void    IORWLockWrite( IORWLock * lock);
 #endif  /* !IOLOCKS_INLINE */
 
 void    IORWLockWrite( IORWLock * lock);
 #endif  /* !IOLOCKS_INLINE */
 

+/*! @function IORWLockTryWrite
+ *   @abstract Attempt to lock a read/write lock for write.
+ *   @discussion Lock the lock for write, allowing one writer exlusive access. If the lock is held for read or write, return false. Return true otherwise.
+ *   @param lock Pointer to the allocated lock. */
+
+#ifdef  IOLOCKS_INLINE
+#define IORWLockTryWrite(l)        lck_rw_try_lock_exclusive(l)
+#else
+void    IORWLockTryWrite( IORWLock * lock);
+#endif  /* !IOLOCKS_INLINE */
+

 /*! @function IORWLockUnlock
  *   @abstract Unlock a read/write 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.
 /*! @function IORWLockUnlock
  *   @abstract Unlock a read/write 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.


@@ -401,11 +423,18 @@ lck_spin_t * IOSimpleLockGetMachLock( IOSimpleLock * lock);
 
 /*! @function IOSimpleLockInit
  *   @abstract Initialize a spin lock.
 
 /*! @function IOSimpleLockInit
  *   @abstract Initialize a spin lock.

- *   @discussion Initialize an embedded spin lock, to the unlocked state.
+ *   @discussion Initialize a non heap allocated spin lock to the unlocked state. Use this function when your lock is, for example, a member variable. You will need to call IOSimpleLockDestroy when you are finished with the lock to avoid lock group refcount leaks.

  *   @param lock Pointer to the lock. */
 
 void IOSimpleLockInit( IOSimpleLock * lock );
 
  *   @param lock Pointer to the lock. */
 
 void IOSimpleLockInit( IOSimpleLock * lock );
 

+/*! @function IOSimpleLockDestroy
+ *   @abstract De-initializes (destroys) a spin lock initialized with IOSimpleLockInit
+ *   @discussion Destroy / De-initialize a non heap allocated spin lock, releasing any system resources such as lock group refcounts.
+ *   @param lock Pointer to the lock. */
+
+void IOSimpleLockDestroy( IOSimpleLock * lock );
+

 /*! @function IOSimpleLockLock
  *   @abstract Lock a spin 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.
 /*! @function IOSimpleLockLock
  *   @abstract Lock a spin 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.