vlc | branch: master | Rémi Denis-Courmont <[email protected]> | Sun Nov 27 18:16:52 2016 +0200| [8f2629d9d2800d621a1456d773686bed3589fd7d] | committer: Rémi Denis-Courmont
playlist: add/fix some documentation > http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=8f2629d9d2800d621a1456d773686bed3589fd7d --- include/vlc_playlist.h | 96 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 71 insertions(+), 25 deletions(-) diff --git a/include/vlc_playlist.h b/include/vlc_playlist.h index a3cd171..b602345 100644 --- a/include/vlc_playlist.h +++ b/include/vlc_playlist.h @@ -44,25 +44,25 @@ struct intf_thread_t; * The VLC playlist system has a tree structure. This allows advanced * categorization, like for SAP streams (which are grouped by "sap groups"). * - * The base structure for all playlist operations is the input_item_t. This - * contains all information needed to play a stream and get info, ie, mostly, - * mrl and metadata. + * The base structure for all playlist operations is the playlist_item_t. + * This is essentially a node within the playlist tree. Each playlist item + * references an input_item_t which contain the input stream infos, such as + * location, name and meta-data. * - * Input items are not used directly, but through playlist items. - * The playlist items are themselves in a tree structure. They only contain - * a link to the input item, a unique id and a few flags. - * Several playlist items can be attached to a single input item. The input - * item is refcounted and is automatically destroyed when it is not used - * anymore. + * A playlist item is uniquely identified by its input item: + * \ref playlist_ItemGetByInput(). A single input item cannot be used by more + * than one playlist item at a time; if necessary, a copy of the input item can + * be made instead. * - * The top-level items are the main media sources and include: - * playlist, media library, SAP, Shoutcast, devices, ... + * The same playlist tree is visible to all user interfaces. To arbitrate + * access, a lock is used, see \ref playlist_Lock() and \ref playlist_Unlock(). * - * It is envisioned that a third tree will appear: VLM, but it's not done yet - * - * The playlist also stores, for utility purposes, an array of all input - * items, an array of all playlist items and an array of all playlist items - * and nodes (both are represented by the same structure). + * The under the playlist root item node, the top-level items are the main + * media sources and include: + * - the actual playlist, + * - the media library, + * - the service discovery root node, whose children are services discovery + * module instances. * * So, here is an example: * \verbatim @@ -79,23 +79,23 @@ struct intf_thread_t; * \endverbatim * * Sometimes, an item creates subitems. This happens for the directory access - * for example. In that case, if the item is under the "playlist" top-level item - * and playlist is configured to be flat then the item will be deleted and + * for example. In that case, if the item is under the "playlist" top-level + * item and playlist is configured to be flat then the item will be deleted and * replaced with new subitems. If the item is under another top-level item, it * will be transformed to a node and removed from the list of all items without * nodes. * - * For "standard" item addition, you can use playlist_Add, playlist_AddExt - * (more options) or playlist_AddInput if you already created your input + * For "standard" item addition, you can use playlist_Add(), playlist_AddExt() + * (more options) or playlist_AddInput() if you already created your input * item. This will add the item at the root of "Playlist" or of "Media library" * in each of the two trees. * - * You can create nodes with playlist_NodeCreate and can create items from - * existing input items to be placed under any node with playlist_NodeAddInput. + * You can create nodes with playlist_NodeCreate() and can create items from + * existing input items to be placed under any node with + * playlist_NodeAddInput(). * * To delete an item, use playlist_NodeDelete( p_item ). * - * * The playlist defines the following event variables: * * - "item-change": It will contain a pointer to the input_item_t of a @@ -108,8 +108,8 @@ struct intf_thread_t; * - "leaf-to-parent": It will contain the playlist_item_t->i_id of an item that is transformed * into a node. * - * The playlist contains rate-variable which is propagated to current input if available - * also rate-slower/rate-faster is in use + * The playlist contains rate-variable which is propagated to current input if + * available also rate-slower/rate-faster is in use. */ /** Helper structure to export to file part of the playlist */ @@ -244,8 +244,54 @@ enum { #define playlist_Resume(p) \ playlist_Control(p, PLAYLIST_RESUME, pl_Unlocked) +/** + * Locks the playlist. + * + * This function locks the playlist. While the playlist is locked, no other + * thread can modify the playlist tree layout or current playing item and node. + * + * Locking the playlist is necessary before accessing, either for reading or + * writing, any playlist item. + * + * \note Because of the potential for lock inversion / deadlocks, locking the + * playlist shall not be attemped while holding an input item lock. An input + * item lock can be acquired while holding the playlist lock. + * + * While holding the playlist lock, a thread shall not attempt to: + * - probe, initialize or deinitialize a module or a plugin, + * - install or deinstall a variable or event callback, + * - set a variable or trigger a variable callback, with the sole exception + * of the playlist core triggerting add/remove/leaf item callbacks, + * - invoke a module/plugin callback other than: + * - playlist export, + * - logger message callback. + */ VLC_API void playlist_Lock( playlist_t * ); + +/** + * Unlocks the playlist. + * + * This function unlocks the playlist, allowing other threads to lock it. The + * calling thread must have called playlist_Lock() before. + * + * This function invalidates all or any playlist item pointers. + * There are no ways to ensure that playlist item are not modified or deleted + * by another thread past this function call. + * + * To retain a reference to a playlist item while not holding the playlist + * lock, a thread should take a reference to the input item within the + * playlist item before unlocking. If this is not practical, then the thread + * can store the playlist item ID (i_id) before unlocking. + * Either way, this will not ensure that the playlist item is not deleted, so + * the thread must be ready to handle that case later when calling + * playlist_ItemGetByInput() or playlist_ItemGetById(). + * + * Furthermore, if ID is used, then the playlist item might be deleted, and + * another item could be assigned the same ID. To avoid that problem, use + * the input item instead of the ID. + */ VLC_API void playlist_Unlock( playlist_t * ); + VLC_API void playlist_AssertLocked( playlist_t * ); VLC_API void playlist_Deactivate( playlist_t * ); _______________________________________________ vlc-commits mailing list [email protected] https://mailman.videolan.org/listinfo/vlc-commits
