[vlc-devel] commit: vlc_object_get sucks, document it ( Rémi Denis-Courmont )

[git version control]

vlc | branch: master | Rémi Denis-Courmont <rem at videolan.org> | Sat May 17 18:58:36 2008 +0300| [d88c98753b29b02bfdb6599a847c3a6f48153b4c]

vlc_object_get sucks, document it

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

 src/misc/objects.c |   11 +++++++----
 1 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/misc/objects.c b/src/misc/objects.c
index 29a3bd2..f248997 100644
--- a/src/misc/objects.c
+++ b/src/misc/objects.c
@@ -661,11 +661,14 @@ void __vlc_object_kill( vlc_object_t *p_this )
 
 
 /**
- * find an object given its ID
+ * Find an object given its ID.
  *
- * This function looks for the object whose i_object_id field is i_id. We
- * use a dichotomy so that lookups are in log2(n).
- *****************************************************************************/
+ * This function looks for the object whose i_object_id field is i_id.
+ * This function is slow, and often used to hide bugs. Do not use it.
+ * If you need to retain reference to an object, yield the object pointer with
+ * vlc_object_yield(), use the pointer as your reference, and call
+ * vlc_object_release() when you're done.
+ */
 void * vlc_object_get( int i_id )
 {
     int i_max, i_middle;