From: Rémi Denis-Courmont Date: Mon, 8 Sep 2008 16:08:07 +0000 (+0300) Subject: Improve documentation X-Git-Tag: 1.0.0-pre1~3431 X-Git-Url: https://git.videolan.org/gitweb.cgi/vlc.git/?p=vlc.git;p=vlc.git;a=commitdiff_plain;h=32c21f4098b3a4c46ab443cba72a8f5abf7c38a6 Improve documentation --- 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 ) {