[vlc-devel] commit: Improve documentation ( Rémi Denis-Courmont )

[git version control]

vlc | branch: master | Rémi Denis-Courmont <rdenis at simphalempin.com> | Mon Sep  8 19:08:07 2008 +0300| [32c21f4098b3a4c46ab443cba72a8f5abf7c38a6] | committer: Rémi Denis-Courmont 

Improve documentation

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=32c21f4098b3a4c46ab443cba72a8f5abf7c38a6
---

 src/misc/objects.c |   28 ++++++++++++----------------
 1 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/src/misc/objects.c b/src/misc/objects.c
index 7782245..4a9f75a 100644
--- a/src/misc/objects.c
+++ b/src/misc/objects.c
@@ -464,16 +464,14 @@ int __vlc_object_waitpipe( vlc_object_t *obj )
 
 
 /**
- * Waits for the object to be signaled (using vlc_object_signal()).
- * It is assumed that the caller has locked the object. This function will
- * unlock the object, and lock it again before returning.
- * If the object was signaled before the caller locked the object, it is
- * undefined whether the signal will be lost or will wake the process.
+ * Suspends until another thread calls vlc_object_signal_unlocked().
+ * The thread may be woken up earlier due to limitations of the underlying
+ * implementation.
+ *
+ * In new code, please use vlc_cond_wait() instead.
  *
  * This function is a cancellation point. In case of cancellation, the object
  * will be in locked state.
- *
- * @return true if the object is dying and should terminate.
  */
 void __vlc_object_wait( vlc_object_t *obj )
 {
@@ -484,11 +482,9 @@ void __vlc_object_wait( vlc_object_t *obj )
 
 
 /**
- * Waits for the object to be signaled (using vlc_object_signal()), or for
- * a timer to expire. It is asserted that the caller holds the object lock.
+ * Same as vlc_object_wait(), with an additional time-out.
  *
- * This function is a cancellation point. In case of cancellation, the object
- * will be in locked state.
+ * @param deadline <b>absolute</b> time-out (using the same clock as mdate())
  *
  * @return 0 if the object was signaled before the timer expiration, or
  * ETIMEDOUT if the timer expired without any signal.
@@ -502,11 +498,11 @@ int __vlc_object_timedwait( vlc_object_t *obj, mtime_t deadline )
 
 
 /**
- * Signals an object for which the lock is held.
- * At least one thread currently sleeping in vlc_object_wait() or
- * vlc_object_timedwait() will wake up, assuming that there is at least one
- * such thread in the first place. Otherwise, it is undefined whether the
- * signal will be lost or will wake up one or more thread later.
+ * Wakes up one thread waiting on the object. If no thread are (yet) waiting,
+ * nothing happens.
+ *
+ * Please do not use this function in new code as we are trying to untangle
+ * objects and threads. Use vlc_cond_wait() instead.
  */
 void __vlc_object_signal_unlocked( vlc_object_t *obj )
 {