Changeset 25168 in vbox for trunk/include/iprt

Timestamp:

Dec 3, 2009 2:59:20 PM (15 years ago)

Author:

vboxsync

Message:

IPRT: documentation

Location:

trunk/include/iprt

Files:

• critsect.h (modified) (2 diffs)
• semaphore.h (modified) (5 diffs)

trunk/include/iprt/critsect.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2006-2007 Sun Microsystems, Inc.
+ * Copyright (C) 2006-2009 Sun Microsystems, Inc.
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -42 +42 @@
 /** @defgroup grp_rt_critsect       RTCritSect - Critical Sections
  *
- * A "critical section" synchronization primitive. This can be used to
- * protect a section of code or data to which access must be exclusive.
- * Only one thread can hold access to a critical section at one time.
- *
- * A critical section is a fast write lock; if the critical section is
- * not acquired, then entering it is fast (requires no system call).
+ * "Critical section" synchronization primitives can be used to
+ * protect a section of code or data to which access must be exclusive;
+ * only one thread can hold access to a critical section at one time.
+ *
+ * A critical section is a fast recursive write lock; if the critical
+ * section is not acquired, then entering it is fast (requires no system
+ * call). IPRT uses the Windows terminology here; on other platform, this
+ * might be called a "futex" or a "fast mutex". As opposed to IPRT
+ * "fast mutexes" (see @ref grp_rt_sems_fast_mutex ), critical sections
+ * are recursive.
  *
  * Use RTCritSectInit to initialize a critical section; use RTCritSectEnter
- * and RTCritSectLeave to acquire and release access. IPRT uses the Windows
- * terminology here; on other platform, this might be called a "futex" or a
- * "fast mutex".
- *
- * If you need a read/write semaphore which allows multiple readers
- * but only writer, use RTSEMRW instead.
+ * and RTCritSectLeave to acquire and release access.
+ *
+ * For an overview of all types of synchronization primitives provided
+ * by IPRT (event, mutex/fast mutex/read-write mutex semaphores), see
+ * @ref grp_rt_sems .
  *
  * @ingroup grp_rt

trunk/include/iprt/semaphore.h

@@ -38 +38 @@
 
 /** @defgroup grp_rt_sems    RTSem - Semaphores
+ *
+ * This module implements all kinds of event and mutex semaphores; in addition
+ * to these, IPRT implements "critical sections", which are fast recursive
+ * mutexes (see @ref grp_rt_critsect ).
+ *
  * @ingroup grp_rt
  * @{
@@ -44 +49 @@
 
 /** @defgroup grp_rt_sems_event    RTSemEvent - Single Release Event Semaphores
+ *
+ * Event semaphores can be used for inter-process communication when
+ * one thread wants to notify another thread that something happened.
+ * A thread can block ("wait") on an event semaphore until it is
+ * signalled by another thread; see RTSemEventCreate, RTSemEventSignal
+ * and RTSemEventWait.
+ *
  * @{ */
 
@@ -166 +178 @@
 /** @defgroup grp_rt_sems_mutex     RTMutex - Mutex semaphores.
  *
- * @remarks These can be pretty heavy handed. Fast mutexes or critical sections
- *          is usually what you need.
+ * Mutex semaphores protect a section of code or data to which access
+ * must be exclusive. Only one thread can hold access to a critical
+ * section at one time. See RTSemMutexCreate, RTSemMutexRequest and
+ * RTSemMutexRelease.
+ *
+ * @remarks These are less efficient than "fast mutexes" and "critical sections",
+ *          which IPRT implements as well; see @ref grp_rt_sems_fast_mutex and
+ *          @ref grp_rt_critsect .
  *
  * @{ */
@@ -232 +250 @@
 
 /** @defgroup grp_rt_sems_fast_mutex    RTSemFastMutex - Fast Mutex Semaphores
+ *
+ * Fast mutexes work like regular mutexes in that they allow only
+ * a single thread access to a critical piece of code or data.
+ * As opposed to mutexes, they require no syscall if the fast mutex
+ * is not held (like critical sections). Unlike critical sections however,
+ * they are *not* recursive.
+ *
  * @{ */
 
@@ -370 +395 @@
 
 /** @defgroup grp_rt_sem_rw             RTSemRW - Read / Write Semaphores
+ *
+ * Read/write semaphores are a fancier version of mutexes in that they
+ * grant read access to the protected data to several threads
+ * at the same time but allow only one writer at a time. This can make
+ * code scale better at the expense of slightly more overhead in
+ * mutex management.
+ *
  * @{ */