vlc | branch: master | Rémi Denis-Courmont <[email protected]> | 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); + +/** @} */ /** @} */ _______________________________________________ vlc-commits mailing list [email protected] https://mailman.videolan.org/listinfo/vlc-commits
