From 32c21f4098b3a4c46ab443cba72a8f5abf7c38a6 Mon Sep 17 00:00:00 2001 From: =?utf8?q?R=C3=A9mi=20Denis-Courmont?= Date: Mon, 8 Sep 2008 19:08:07 +0300 Subject: [PATCH] Improve documentation --- src/misc/objects.c | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/src/misc/objects.c b/src/misc/objects.c index 778224574e..4a9f75ad94 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 absolute 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 ) { -- 2.20.1