VLC 4.0.0-dev
Loading...
Searching...
No Matches
vlc_objects.h
Go to the documentation of this file.
1/*****************************************************************************
2 * vlc_objects.h: vlc_object_t definition and manipulation methods
3 *****************************************************************************
4 * Copyright (C) 2002-2008 VLC authors and VideoLAN
5 *
6 * Authors: Samuel Hocevar <sam@zoy.org>
7 *
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation; either version 2.1 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21 *****************************************************************************/
22
23#ifndef VLC_OBJECTS_H
24#define VLC_OBJECTS_H 1
25
26#ifdef __cplusplus
27#include <new>
28extern "C" {
29#endif
30
31/**
32 * \defgroup vlc_object VLC objects
33 * \ingroup vlc
34 * @{
35 * \file
36 * Common VLC object definitions
37 */
38
39struct vlc_logger;
40struct vlc_tracer;
42struct vlc_object_marker;
43
44/**
45 * VLC object common members
46 *
47 * Common public properties for all VLC objects.
48 * Object also have private properties maintained by the core, see
49 * \ref vlc_object_internals_t
50 */
51struct vlc_object_t
53 struct vlc_logger *logger;
54 union {
55 struct vlc_object_internals *priv;
56 struct vlc_object_marker *obj;
57 };
58
59 bool no_interact;
61 /** Module probe flag
62 *
63 * A boolean during module probing when the probe is "forced".
64 * See \ref module_need().
65 */
66 bool force;
67};
68
69#ifdef __cplusplus
70}
71#endif
72
73/**
74 * Type-safe vlc_object_t cast
75 *
76 * This macro attempts to cast a pointer to a compound type to a
77 * \ref vlc_object_t pointer in a type-safe manner.
78 * It checks if the compound type actually starts with an embedded
79 * \ref vlc_object_t structure.
80 */
81#if !defined(__cplusplus)
82# define VLC_OBJECT(x) \
83 _Generic((x)->obj, \
84 struct vlc_object_marker *: (x), \
85 struct vlc_object_t: (&((x)->obj)) \
86 )
87#else
88static inline vlc_object_t *VLC_OBJECT(vlc_object_t *o)
89 { return o; }
90
91template<typename T>
92static inline vlc_object_t *VLC_OBJECT(T *d)
93 { return &d->obj; }
94#endif
95
96#ifdef __cplusplus
97extern "C" {
98#endif
99
100/* The root object */
101struct libvlc_int_t
103 struct vlc_object_t obj;
105
106/**
107 * Allocates and initializes a vlc object.
108 *
109 * The object will need to be released with ::vlc_object_release()
110 * before \p parent is released.
111 *
112 * @param parent A parent object to create the new object from
113 * @param i_size object byte size
114 *
115 * @return the new object, or NULL on error.
116 */
117VLC_API void *vlc_object_create(vlc_object_t *parent, size_t i_size) VLC_MALLOC VLC_USED;
118
119/**
120 * Drops the strong reference to an object.
121 *
122 * This removes the initial strong reference to a given object. This must be
123 * called exactly once per allocated object after it is no longer needed,
124 * matching vlc_object_create() or vlc_custom_create().
125 */
127#define vlc_object_delete(obj) vlc_object_delete(VLC_OBJECT(obj))
131/**
132 * Returns the object type name.
133 *
134 * This returns a nul-terminated string identifying the object type.
135 * The string is valid for at least as long as the object reference.
136 *
137 * \param obj object whose type name to get
138 */
140
141/**
142 * Gets the parent of an object.
143 *
144 * \return the parent object (NULL if none)
145 *
146 * \note The returned parent object pointer is valid as long as the child is.
147 */
149#define vlc_object_parent(o) vlc_object_parent(VLC_OBJECT(o))
151static inline struct vlc_logger *vlc_object_logger(vlc_object_t *obj)
153 return obj->logger;
154}
155#define vlc_object_logger(o) vlc_object_logger(VLC_OBJECT(o))
157 /**
158 * Get tracer of a vlc instance from an object.
159 *
160 * \return the tracer of a vlc instance from an object (NULL if none).
161 */
163
164/**
165 * Tries to get the name of module bound to an object.
166 *
167 * \warning This function is intrinsically race-prone, as a module may be
168 * bound or unbound asynchronously by another thread.
169 * Do not trust the result for any purpose other than debugging/tracing.
170 *
171 * \return Normally, this returns a heap-allocated nul-terminated string
172 * which is the name of the module. If no module are bound to the object, it
173 * returns NULL. It also returns NULL on error.
174 */
175#define vlc_object_get_name(obj) var_GetString(obj, "module-name")
177#define vlc_object_create(a,b) vlc_object_create( VLC_OBJECT(a), b )
179#define vlc_object_find_name(a,b) \
180 vlc_object_find_name( VLC_OBJECT(a),b)
181
185 vlc_object_t *parent;
186
187 do
188 parent = obj;
189 while ((obj = vlc_object_parent(obj)) != NULL);
190
191 return (libvlc_int_t *)parent;
192}
193#define vlc_object_instance(o) vlc_object_instance(VLC_OBJECT(o))
195/* Here for backward compatibility. TODO: Move to <vlc_vout.h>! */
198
199/* Here for backward compatibility. TODO: Move to <vlc_aout.h>! */
202
203/* TODO: remove vlc_object_hold/_release() for GUIs, remove this */
204VLC_DEPRECATED static inline void *vlc_object_hold(vlc_object_t *o)
206 const char *tn = vlc_object_typename(o);
207
208 if (!strcmp(tn, "audio output"))
210 if (!strcmp(tn, "video output"))
212 return o;
213}
214
215static inline void vlc_object_release(vlc_object_t *o)
217 const char *tn = vlc_object_typename(o);
218
219 if (!strcmp(tn, "audio output"))
221 if (!strcmp(tn, "video output"))
223}
224#define vlc_object_release(o) vlc_object_release(VLC_OBJECT(o))
226/**
227 * @defgroup objres Object resources
228 *
229 * The object resource functions tie resource allocation to an instance of
230 * a module through a VLC object.
231 * Such resource will be automatically freed, in first in last out order,
232 * when the module instance associated with the VLC object is terminated.
233 *
234 * Specifically, if the module instance activation/probe function fails, the
235 * resource will be freed immediately after the failure. If the activation
236 * succeeds, the resource will be freed when the module instance is terminated.
237 *
238 * This is a convenience mechanism to save explicit clean-up function calls
239 * in modules.
240 *
241 * @{
242 */
243
244/**
245 * Allocates memory for a module.
246 *
247 * This function allocates memory from the heap for a module instance.
248 * The memory is uninitialized.
249 *
250 * @param obj VLC object to tie the memory allocation to
251 * @param size byte size of the memory allocation
252 *
253 * @return a pointer to the allocated memory, or NULL on error (errno is set).
254 */
255VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *obj, size_t size);
256#define vlc_obj_malloc(o, s) vlc_obj_malloc(VLC_OBJECT(o), s)
258/**
259 * Allocates a zero-initialized table for a module.
260 *
261 * This function allocates a table from the heap for a module instance.
262 * The memory is initialized to all zeroes.
263 *
264 * @param obj VLC object to tie the memory allocation to
265 * @param nmemb number of table entries
266 * @param size byte size of a table entry
267 *
268 * @return a pointer to the allocated memory, or NULL on error (errno is set).
269 */
270VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *obj, size_t nmemb,
271 size_t size);
272#define vlc_obj_calloc(o, n, s) vlc_obj_calloc(VLC_OBJECT(o), n, s)
274/**
275 * Duplicates a string for a module.
276 *
277 * This function allocates a copy of a nul-terminated string for a module
278 * instance.
279 *
280 * @param obj VLC object to tie the memory allocation to
281 * @param str string to copy
282 *
283 * @return a pointer to the copy, or NULL on error (errno is set).
284 */
285VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *obj, const char *str);
286#define vlc_obj_strdup(o, s) vlc_obj_strdup(VLC_OBJECT(o), s)
288/**
289 * Manually frees module memory.
290 *
291 * This function manually frees a resource allocated with vlc_obj_malloc(),
292 * vlc_obj_calloc() or vlc_obj_strdup() before the module instance is
293 * terminated. This is seldom necessary.
294 *
295 * @param obj VLC object that the allocation was tied to
296 * @param ptr pointer to the allocated resource
297 */
298VLC_API void vlc_obj_free(vlc_object_t *obj, void *ptr);
299#define vlc_obj_free(o, p) vlc_obj_free(VLC_OBJECT(o), p)
301#ifdef __cplusplus
302} /* extern "C" */
303
304# include <type_traits>
305
306#undef vlc_object_create
307
308template <typename O> VLC_MALLOC VLC_USED
309static inline void* vlc_object_create(O *obj, size_t size)
310{
311 return vlc_object_create(VLC_OBJECT(obj), size);
312}
313
314template<typename T, typename O> VLC_MALLOC VLC_USED
315static inline T* vlc_object_create(O *obj)
316{
317 static_assert(std::is_pointer<T>::value == false, "vlc_object_create can only create objects");
318 void *object = vlc_object_create(VLC_OBJECT(obj), sizeof(T));
319 if (object == nullptr)
320 return nullptr;
321
322 return new(object) T;
323}
324
325#undef vlc_object_delete
326template<typename O>
327static inline void vlc_object_delete(O *obj)
328{
329 if (!std::is_trivially_destructible<O>::value)
330 obj->~O();
332}
333
334#endif
335
336/** @} */
337/** @} */
338
339#endif
#define VLC_USED
Definition fourcc_gen.c:32
#define VLC_API
Definition fourcc_gen.c:31
#define VLC_MALLOC
Definition vlc_common.h:157
#define VLC_DEPRECATED
Definition vlc_common.h:158
#define vlc_obj_calloc(o, n, s)
Definition vlc_objects.h:273
#define vlc_obj_malloc(o, s)
Definition vlc_objects.h:257
#define vlc_obj_free(o, p)
Definition vlc_objects.h:300
#define vlc_obj_strdup(o, s)
Definition vlc_objects.h:287
#define VLC_OBJECT(x)
Type-safe vlc_object_t cast.
Definition vlc_objects.h:83
#define vlc_object_create(a, b)
Definition vlc_objects.h:178
vout_thread_t * vout_Hold(vout_thread_t *vout)
Definition video_output.c:2137
struct vlc_tracer * vlc_object_get_tracer(vlc_object_t *obj)
Get tracer of a vlc instance from an object.
Definition objects.c:120
#define vlc_object_release(o)
Definition vlc_objects.h:225
#define vlc_object_delete(obj)
Definition vlc_objects.h:128
#define vlc_object_logger(o)
Definition vlc_objects.h:156
void aout_Release(audio_output_t *aout)
Definition output.c:436
const char * vlc_object_typename(const vlc_object_t *obj)
Returns the object type name.
Definition objects.c:110
audio_output_t * aout_Hold(audio_output_t *aout)
Definition output.c:392
static void * vlc_object_hold(vlc_object_t *o)
Definition vlc_objects.h:205
size_t vlc_list_children(vlc_object_t *, vlc_object_t **, size_t)
#define vlc_object_parent(o)
Definition vlc_objects.h:150
#define vlc_object_instance(o)
Definition vlc_objects.h:194
void vout_Release(vout_thread_t *vout)
Definition video_output.c:1983
Audio output object.
Definition vlc_aout.h:155
Definition vlc_objects.h:103
struct vlc_object_t obj
Definition vlc_objects.h:104
Definition messages.c:85
Definition variables.h:36
VLC object common members.
Definition vlc_objects.h:53
struct vlc_logger * logger
Definition vlc_objects.h:54
struct vlc_object_marker * obj
Definition vlc_objects.h:57
bool no_interact
Definition vlc_objects.h:60
bool force
Module probe flag.
Definition vlc_objects.h:67
struct vlc_object_internals * priv
Definition vlc_objects.h:56
Definition tracer.c:36
Video output thread descriptor.
Definition vlc_vout.h:54
This file is a collection of common definitions and types.