Hacker Guide/Object Management - Revision history

DoesItReallyMatter: Lc/e

2019-04-17T06:53:58Z

Lc/e

← Older revision		Revision as of 06:53, 17 April 2019
Line 1:		Line 1:
	{{Back to\|Hacker Guide}}		{{Back to\|Hacker Guide}}
	== VLC Object Management ==		== VLC Object Management ==


	=== Introduction ===		=== Introduction ===

	This paper will discuss VLC objects and the general object oriented practices involved in developing and extending libvlc.		This paper will discuss VLC objects and the general [[wikipedia:Object-oriented programming\|object oriented]] practices involved in developing and extending [[libvlc]].

	=== Object Creation ===		=== 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 [~~http~~://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html include/vlc_objects.h].		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 [https://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html include/vlc_objects.h].

	; <code>vlc_object_create()</code>		; <code>vlc_object_create()</code>
Line 22:		Line 21:
	=== Inheritance ===		=== Inheritance ===

	Objects can have multiple levels of inheritance. Each object is represented by the type <code>[~~http~~://www.videolan.org/developers/vlc/doc/doxygen/html/structvlc__object__t.html vlc_object_t]</code>. 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 (<code>VLC_COMMON_MEMBERS</code>) inside each inherited object structure. For example, a libvlc instance of type <code>libvlc_int_t</code> inherits from <code>vlc_object_t</code> by embedding the <code>VLC_COMMON_MEMBERS</code> inside the <code>libvlc_int_t</code> structure as seen in example 1 below.		Objects can have multiple levels of inheritance. Each object is represented by the type <code>[https://www.videolan.org/developers/vlc/doc/doxygen/html/structvlc__object__t.html vlc_object_t]</code>. 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 (<code>VLC_COMMON_MEMBERS</code>) inside each inherited object structure. For example, a libvlc instance of type <code>libvlc_int_t</code> inherits from <code>vlc_object_t</code> by embedding the <code>VLC_COMMON_MEMBERS</code> inside the <code>libvlc_int_t</code> structure as seen in example 1 below.


	<u>Example 1:</u> libvlc_int_t : vlc_object_t		<u>Example 1:</u> libvlc_int_t : vlc_object_t
	<~~pre~~>		<syntaxhighlight lang="c">
	struct libvlc_int_t		struct libvlc_int_t
	{		{
Line 33:		Line 32:
	/* Everything Else */		/* Everything Else */
	}		}
	</~~pre~~>		</syntaxhighlight>

	=== Reference Counts ===		=== Reference Counts ===

	In order to simplify garbage collection, every object has a reference count. When an object is created (<code>malloc()</code>'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 (<code>free()</code>) 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 [~~http~~://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html ~~<tt>~~include/vlc_objects.h~~</tt>~~].		In order to simplify garbage collection, every object has a reference count. When an object is created (<code>malloc()</code>'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 (<code>free()</code>) 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 [https://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html include/vlc_objects.h].

	; <code>vlc_object_hold()</code>		; <code>vlc_object_hold()</code>
	: 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!		: 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!

	; <code>vlc_object_release()</code>		; <code>vlc_object_release()</code>
	: 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!		: 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!

	{{Hacker_Guide}}		{{Hacker_Guide}}

DoesItReallyMatter: +{{Back to|Hacker Guide}}

2019-04-17T03:48:07Z

+{{Back to|Hacker Guide}}

← Older revision		Revision as of 03:48, 17 April 2019
Line 1:		Line 1:
			{{Back to\|Hacker Guide}}
	== VLC Object Management ==		== VLC Object Management ==

EPirat: /* Reference Counts */

2017-01-23T19:21:47Z

Reference Counts

← Older revision		Revision as of 19:21, 23 January 2017
Line 36:		Line 36:
	=== Reference Counts ===		=== 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 [http://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html include/vlc_objects.h].		In order to simplify garbage collection, every object has a reference count. When an object is created (<code>malloc()</code>'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 (<code>free()</code>) 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 [http://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html <tt>include/vlc_objects.h</tt>].

	''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!		; <code>vlc_object_hold()</code>
			: 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!		; <code>vlc_object_release()</code>
			: 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!

	{{Hacker_Guide}}		{{Hacker_Guide}}

EPirat: /* Inheritance */

2017-01-23T19:20:01Z

Inheritance

← Older revision		Revision as of 19:20, 23 January 2017
Line 21:		Line 21:
	=== Inheritance ===		=== 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.		Objects can have multiple levels of inheritance. Each object is represented by the type <code>[http://www.videolan.org/developers/vlc/doc/doxygen/html/structvlc__object__t.html vlc_object_t]</code>. 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 (<code>VLC_COMMON_MEMBERS</code>) inside each inherited object structure. For example, a libvlc instance of type <code>libvlc_int_t</code> inherits from <code>vlc_object_t</code> by embedding the <code>VLC_COMMON_MEMBERS</code> inside the <code>libvlc_int_t</code> structure as seen in example 1 below.

EPirat: /* Object Creation */

2017-01-23T19:14:58Z

Object Creation

← Older revision		Revision as of 19:14, 23 January 2017
Line 10:		Line 10:
	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 [http://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html include/vlc_objects.h].		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 [http://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__objects_8h.html include/vlc_objects.h].

	''vlc_object_create()~~'' - create~~ an object and set its refcount to 0		; <code>vlc_object_create()</code>
			: Create an object and set its refcount to 0
	''vlc_object_destroy()~~'' - de~~-allocate an object iff its refcount = 0		; <code>vlc_object_destroy()</code>
			: De-allocate an object iff its refcount = 0
	''vlc_object_attach()~~'' - bidirectionally~~ link an object with its parent		; <code>vlc_object_attach()</code>
			: Bidirectionally link an object with its parent
	''vlc_object_detach()~~'' - remove~~ all links between an object and its parent		; <code>vlc_object_detach()</code>
			: Remove all links between an object and its parent

	=== Inheritance ===		=== Inheritance ===

Corbax: /* Reference Counts */

2013-11-14T17:26:24Z

Reference Counts

← Older revision		Revision as of 17:26, 14 November 2013
Line 41:		Line 41:
	''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!		''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!

	~~[[Category:Coding]]~~
	{{Hacker_Guide}}		{{Hacker_Guide}}

Corbax at 16:21, 30 October 2013

2013-10-30T16:21:21Z

← Older revision		Revision as of 16:21, 30 October 2013
Line 42:		Line 42:

	[[Category:Coding]]		[[Category:Coding]]
	{{~~Documentation~~}}		{{Hacker_Guide}}

Corbax: /* Reference Counts */

2013-10-01T14:47:46Z

Reference Counts

← Older revision		Revision as of 14:47, 1 October 2013
Line 41:		Line 41:
	''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!		''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!

			[[Category:Coding]]
	{{Documentation}}		{{Documentation}}

J-b: moved Documentation:Hacker's Guide/Object Management to Hacker Guide/Object Management

2011-11-09T11:48:06Z

moved Documentation:Hacker's Guide/Object Management to Hacker Guide/Object Management

← Older revision	Revision as of 11:48, 9 November 2011
(No difference)

Courmisch: /* Mutexes */

2011-10-16T11:35:26Z

Mutexes

← Older revision		Revision as of 11:35, 16 October 2011
Line 40:		Line 40:

	''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!		''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!

	~~=== 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 [http://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__threads_8h.html include/vlc_threads.h].


	~~<u>Example 2:</u> vlc_mutex_t~~
	~~<pre>~~
	~~typedef struct~~
	{
	~~pthread_mutex_t mutex; /* OS primitive */~~
	~~vlc_object_t * p_this; /* pointer to object that mutex protects */~~
	~~} vlc_mutex_t;~~
	~~</pre>~~

	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 [http://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__threads__funcs_8h.html 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~~


	{{Documentation}}		{{Documentation}}