[vlc-commits] [Git][videolan/vlc][master] threads: update documentation

[Rémi Denis-Courmont (@Courmisch)]

Rémi Denis-Courmont pushed to branch master at VideoLAN / VLC


Commits:
1f137b77 by Rémi Denis-Courmont at 2021-10-27T15:21:50+00:00
threads: update documentation

As briefly noted in 0a8a53335b5770cd1acaa612b495bdbc41a8d1ee, that
changeset removed the confusing and messy limitations of mutex
assertions. Previously, it would only work if:
- checking for hold, not for non-hold,
- POSIX threads was used,
- LibVLC was built in debug mode,
- the mutex was initialised dynamically (not `VLC_STATIC_MUTEX`).

- - - - -


1 changed file:

- include/vlc_threads.h


Changes:

=====================================
include/vlc_threads.h
=====================================
@@ -306,13 +306,16 @@ VLC_API void vlc_mutex_unlock(vlc_mutex_t *);
 /**
  * Checks if a mutex is locked.
  *
- * Do not use this function directly. Use vlc_mutex_assert() instead.
+ * This function checks if the calling thread holds a given mutual exclusion
+ * lock. It has no side effects and is essentially intended for run-time
+ * debugging.
  *
- * @note
- * This function has no effects.
- * It is only meant to be use in run-time assertions.
+ * @note To assert that the calling thread holds a lock, the helper macro
+ * vlc_mutex_assert() should be used instead of this function.
  *
- * @warning This function might not return correct results in non-debug builds.
+ * @note While it is nominally possible to implement recursive lock semantics
+ * with this function, vlc_mutex_init_recursive() should be used instead to
+ * create a recursive mutex explicitly..
  *
  * @retval false the mutex is not locked by the calling thread
  * @retval true the mutex is locked by the calling thread



View it on GitLab: https://code.videolan.org/videolan/vlc/-/commit/1f137b77389b535892f673f57fd37b7d8299c7fa

-- 
View it on GitLab: https://code.videolan.org/videolan/vlc/-/commit/1f137b77389b535892f673f57fd37b7d8299c7fa
You're receiving this email because of your account on code.videolan.org.