demux: ts: proper init/clean for fmt in hotfixes
[vlc.git] / src / misc / background_worker.h
blob30792fa3ed6210eec39ce43da958b70c956580fa
1 /*****************************************************************************
2 * Copyright (C) 2017 VLC authors and VideoLAN
4 * This program is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation; either version 2.1 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this program; if not, write to the Free Software Foundation,
16 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
17 *****************************************************************************/
19 #ifndef BACKGROUND_WORKER_H__
20 #define BACKGROUND_WORKER_H__
22 struct background_worker_config {
23 /**
24 * Default timeout for completing a task
26 * If less-than 0 a task can run indefinitely without being killed, whereas
27 * a positive value denotes the maximum number of milliseconds a task can
28 * run before \ref pf_stop is called to kill it.
29 **/
30 mtime_t default_timeout;
32 /**
33 * Release an entity
35 * This callback will be called in order to decrement the ref-count of a
36 * entity within the background-worker. It will happen either when \ref
37 * pf_stop has finished executing, or if the entity is removed from the
38 * queue (through \ref background_worker_Cancel)
40 * \param entity the entity to release
41 **/
42 void( *pf_release )( void* entity );
44 /**
45 * Hold a queued item
47 * This callback will be called in order to increment the ref-count of an
48 * entity. It will happen when the entity is pushed into the queue of
49 * pending tasks as part of \ref background_worker_Push.
51 * \param entity the entity to hold
52 **/
53 void( *pf_hold )( void* entity );
55 /**
56 * Start a new task
58 * This callback is called in order to construct a new background task. In
59 * order for the background-worker to be able to continue processing
60 * incoming requests, \ref pf_start is meant to start a task (such as a
61 * thread), and then store the associated handle in `*out`.
63 * The value of `*out` will then be the value of the argument named `handle`
64 * in terms of \ref pf_probe and \ref pf_stop.
66 * \param owner the owner of the background-worker
67 * \param entity the entity for which a task is to be created
68 * \param out [out] `*out` shall, on success, refer to the handle associated
69 * with the running task.
70 * \return VLC_SUCCESS if a task was created, an error-code on failure.
71 **/
72 int( *pf_start )( void* owner, void* entity, void** out );
74 /**
75 * Probe a running task
77 * This callback is called in order to see whether or not a running task has
78 * finished or not. It can be called anytime between a successful call to
79 * \ref pf_start, and the corresponding call to \ref pf_stop.
81 * \param owner the owner of the background-worker
82 * \param handle the handle associated with the running task
83 * \return 0 if the task is still running, any other value if finished.
84 **/
85 int( *pf_probe )( void* owner, void* handle );
87 /**
88 * Stop a running task
90 * This callback is called in order to stop a running task. If \ref pf_start
91 * has created a non-detached thread, \ref pf_stop is where you would
92 * interrupt and then join it.
94 * \warning This function is called either after \ref pf_probe has stated
95 * that the task has finished, or if the timeout (if any) for the
96 * task has been reached.
98 * \param owner the owner of the background-worker
99 * \parma handle the handle associated with the task to be stopped
101 void( *pf_stop )( void* owner, void* handle );
105 * Create a background-worker
107 * This function creates a new background-worker using the passed configuration.
109 * \warning all members of `config` shall have been set by the caller.
110 * \warning the returned resource must be destroyed using \ref
111 * background_worker_Delete on success.
113 * \param owner the owner of the background-worker
114 * \param config the background-worker's configuration
115 * \return a pointer-to the created background-worker on success,
116 * `NULL` on failure.
118 struct background_worker* background_worker_New( void* owner,
119 struct background_worker_config* config );
122 * Request the background-worker to probe the current task
124 * This function is used to signal the background-worker that it should do
125 * another probe to see whether the current task is still alive.
127 * \warning Note that the function will not wait for the probing to finish, it
128 * will simply ask the background worker to recheck it as soon as
129 * possible.
131 * \param worker the background-worker
133 void background_worker_RequestProbe( struct background_worker* worker );
136 * Push an entity into the background-worker
138 * This function is used to push an entity into the queue of pending work. The
139 * entities will be processed in the order in which they are received (in terms
140 * of the order of invocations in a single-threaded environment).
142 * \param worker the background-worker
143 * \param entity the entity which is to be queued
144 * \param id a value suitable for identifying the entity, or `NULL`
145 * \param timeout the timeout of the entity in milliseconds, `0` denotes no
146 * timeout, a negative value will use the default timeout
147 * associated with the background-worker.
148 * \return VLC_SUCCESS if the entity was successfully queued, an error-code on
149 * failure.
151 int background_worker_Push( struct background_worker* worker, void* entity,
152 void* id, int timeout );
155 * Remove entities from the background-worker
157 * This function is used to remove processing of a certain entity given its
158 * associated id, or to remove all queued (including currently running)
159 * entities.
161 * \warning if the `id` passed refers to an entity that is currently being
162 * processed, the call will block until the task has been terminated.
164 * \param worker the background-worker
165 * \param id NULL if every entity shall be removed, and the currently running
166 * task (if any) shall be cancelled.
168 void background_worker_Cancel( struct background_worker* worker, void* id );
171 * Delete a background-worker
173 * This function will destroy a background-worker created through \ref
174 * background_worker_New. It will effectively stop the currently running task,
175 * if any, and empty the queue of pending entities.
177 * \warning If there is a currently running task, the function will block until
178 * it has been stopped.
180 * \param worker the background-worker
182 void background_worker_Delete( struct background_worker* worker );
183 #endif