Hacker Guide/Object Management
Contents
VLC Object Management
Introduction
This paper will discuss VLC objects and the general object oriented practices involved in developing and extending libvlc.
Object Creation
In VLC everything is an object. Each object can have a parent and multiple children. The following functions are used for creating an object and attaching to parents and children. Note that this list may not be complete. For reference see the file include/vlc_objects.h.
vlc_object_create() - create an object and set its refcount to 0
vlc_object_destroy() - de-allocate an object iff its refcount = 0
vlc_object_attach() - bidirectionally link an object with its parent
vlc_object_detach() - remove all links between an object and its parent
Inheritance
Objects can have multiple levels of inheritance. Each object is represented by the type vlc_object_t . Every object inherits from this type and can be cast to it. Inheritance is achieved in the C language by embedding a macro of common structure elements (VLC_COMMON_MEMBERS) inside each inherited object structure. For example, a libvlc instance of type libvlc_int_t inherits from vlc_object_t by embedding the VLC_COMMON_MEMBERS inside the libvlc_int_t structure as seen in example 1 below.
Example 1: libvlc_int_t : vlc_object_t
struct libvlc_int_t
{
VLC_COMMON_MEMBERS
/* Everything Else */
}
Reference Counts
In order to simplify garbage collection, every object has a reference count. When an object is created (malloc()'d) its reference count is set to 0. Anytime the object is acquired for use by a caller that caller must increase its reference count by 1. When the caller is done using the object it must decrease the object's reference count by 1. Luckily, most of this is handled by internal object management acquisition and removal functions. In order to destroy (free()) the object the reference count of the object must be 0. The following functions are used to manipulate object reference counts. Note that this list may not be complete. For reference see the file include/vlc_objects.h.
vlc_object_hold() - increase the refcount of an object by 1. This function should only be used in object management functions! Careless usage will lead to memory leaks!
vlc_object_release() - decrease the refcount of an object by 1. This function should only be used in object management functions! Careless usage can lead to early object destruction, while the object may still be in use!
Threads
VLC is a multithreaded application. Thread handling is performed by the following functions. See include/vlc_threads_funcs.h.
vlc_thread_create() - spawn a new thread
vlc_thread_set_priority() - set the priority of a thread
vlc_thread_ready() - alert the parent that we were successfully spawned
vlc_thread_join() - wait for a thread to exit
Mutexes
VLC is a shared-state multithreaded program and as such it requires objects to be protected from concurrency related issues such as race conditions. In order to protect objects a mutex object is used. The mutex is of type vlc_mutex_t and contains a pointer to the object that the mutex is protecting as well as an OS level mutex primitive. See Example 2 below for a sample declaration of vlc_mutex_t under Linux using pthreads. Actual implementations for your OS can be found in include/vlc_threads.h.
Example 2: vlc_mutex_t
typedef struct
{
pthread_mutex_t mutex; /* OS primitive */
vlc_object_t * p_this; /* pointer to object that mutex protects */
} vlc_mutex_t;
Operations on vlc_mutex_t objects are wrapped by VLC to enhance portability. Below is a list of operations on mutex objects. This list is incomplete. See include/vlc_threads_funcs.h.
vlc_mutex_init() - initialize a mutex
vlc_mutex_lock() - lock an object
vlc_mutex_unlock() - unlock an object
vlc_mutex_end() - deinitialize a mutex
Please read the Documentation Editing Guidelines before you edit the documentation
