[vlc-commits] objres: document the functions

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Mon Jul  2 22:25:10 2018 +0300| [6136e5ac674ee97fb07befd369b8a08fbafd8aeb] | committer: Rémi Denis-Courmont

objres: document the functions

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

 include/vlc_objects.h | 76 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 72 insertions(+), 4 deletions(-)

diff --git a/include/vlc_objects.h b/include/vlc_objects.h
index e28d5ea812..43679dd97a 100644
--- a/include/vlc_objects.h
+++ b/include/vlc_objects.h
@@ -131,9 +131,77 @@ VLC_API char *vlc_object_get_name( const vlc_object_t * ) VLC_USED;
 #define vlc_object_release(a) \
     vlc_object_release( VLC_OBJECT(a) )
 
-VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *, size_t);
-VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *, size_t, size_t);
-VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *, const char *);
-VLC_API void vlc_obj_free(vlc_object_t *, void *);
+/**
+ * @defgroup objres Object resources
+ *
+ * The object resource functions tie resource allocation to an instance of
+ * a module through a VLC object.
+ * Such resource will be automatically freed, in first in last out order,
+ * when the module instance associated with the VLC object is terminated.
+ *
+ * Specifically, if the module instance activation/probe function fails, the
+ * resource will be freed immediately after the failure within
+ * vlc_module_load(). If the activation succeeds, the resource will be freed
+ * when the module instance is terminated with vlc_module_unload().
+ *
+ * This is a convenience mechanism to save explicit clean-up function calls
+ * in modules.
+ *
+ * @{
+ */
+
+/**
+ * Allocates memory for a module.
+ *
+ * This function allocates memory from the heap for a module instance.
+ * The memory is uninitialized.
+ *
+ * @param obj VLC object to tie the memory allocation to
+ * @param size byte size of the memory allocation
+ *
+ * @return a pointer to the allocated memory, or NULL on error (errno is set).
+ */
+VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *obj, size_t size);
 
+/**
+ * Allocates a zero-initialized table for a module.
+ *
+ * This function allocates a table from the heap for a module instance.
+ * The memory is initialized to all zeroes.
+ *
+ * @param obj VLC object to tie the memory allocation to
+ * @param nmemb number of table entries
+ * @param size byte size of a table entry
+ *
+ * @return a pointer to the allocated memory, or NULL on error (errno is set).
+ */
+VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *obj, size_t nmemb,
+                                        size_t size);
+
+/**
+ * Duplicates a string for a module.
+ *
+ * This function allocates a copy of a nul-terminated string for a module
+ * instance.
+ *
+ * @param obj VLC object to tie the memory allocation to
+ * @param str string to copy
+ *
+ * @return a pointer to the copy, or NULL on error (errno is set).
+ */
+VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *obj, const char *str);
+
+/**
+ * Manually frees module memory.
+ *
+ * This function manually frees a resource allocated with vlc_obj_malloc(),
+ * vlc_obj_calloc() or vlc_obj_strdup() before the module instance is
+ * terminated. This is seldom necessary.
+ *
+ * @param obj VLC object that the allocation was tied to
+ * @param ptr pointer to the allocated resource
+ */
+VLC_API void vlc_obj_free(vlc_object_t *obj, void *ptr);
+
+/** @} */
 /** @} */