VLC  4.0.0-dev
vlc_executor.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_executor.h
3  *****************************************************************************
4  * Copyright (C) 2020 Videolabs, VLC authors and VideoLAN
5  *
6  * This program is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License as published by
8  * the Free Software Foundation; either version 2.1 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19  *****************************************************************************/
20 
21 #ifndef VLC_EXECUTOR_H
22 #define VLC_EXECUTOR_H
23 
24 #include <vlc_common.h>
25 #include <vlc_list.h>
26 
27 # ifdef __cplusplus
28 extern "C" {
29 # endif
30 
31 /** Executor type (opaque) */
32 typedef struct vlc_executor vlc_executor_t;
33 
34 /**
35  * A Runnable encapsulates a task to be run from an executor thread.
36  */
37 struct vlc_runnable {
38 
39  /**
40  * This function is to be executed by a vlc_executor_t.
41  *
42  * It must implement the actions (arbitrarily long) to execute from an
43  * executor thread, synchronously. As soon as run() returns, the execution
44  * of this runnable is complete.
45  *
46  * After the runnable is submitted to an executor via
47  * vlc_executor_Submit(), the run() function is executed at most once (zero
48  * if the execution is canceled before it was started).
49  *
50  * It must not be NULL.
51  *
52  * \param userdata the userdata provided to vlc_executor_Submit()
53  */
54  void (*run)(void *userdata);
55 
56  /**
57  * Userdata passed back to run().
58  */
59  void *userdata;
60 
61  /* Private data used by the vlc_executor_t (do not touch) */
62  struct vlc_list node;
63 };
64 
65 /**
66  * Create a new executor.
67  *
68  * \param max_threads the maximum number of threads used to execute runnables
69  * \return a pointer to a new executor, or NULL if an error occurred
70  */
72 vlc_executor_New(unsigned max_threads);
73 
74 /**
75  * Delete an executor.
76  *
77  * Wait for all the threads to complete, and delete the executor instance.
78  *
79  * All submitted tasks must be either started or explicitly canceled. To wait
80  * for all tasks to complete, use vlc_executor_WaitIdle().
81  *
82  * It is an error to submit a new runnable after vlc_executor_Delete() is
83  * called. In particular, a running task must not submit a new runnable once
84  * deletion has been requested.
85  *
86  * \param executor the executor
87  */
88 VLC_API void
90 
91 /**
92  * Submit a runnable for execution.
93  *
94  * The struct vlc_runnable is not copied, it must exist until the end of the
95  * execution (the user is expected to embed it in its own task structure).
96  *
97  * Here is a simple example:
98  *
99  * \code{c}
100  * struct my_task {
101  * char *str;
102  * struct vlc_runnable runnable;
103  * };
104  *
105  * static void Run(void *userdata)
106  * {
107  * struct my_task *task = userdata;
108  *
109  * printf("start of %s\n", task->str);
110  * vlc_tick_sleep(VLC_TICK_FROM_SEC(3)); // long action
111  * printf("end of %s\n", task->str);
112  *
113  * free(task->str);
114  * free(task);
115  * }
116  *
117  * void foo(vlc_executor_t *executor, const char *str)
118  * {
119  * // no error handling for brevity
120  * struct my_task *task = malloc(sizeof(*task));
121  * task->str = strdup(str);
122  * task->runnable.run = Run;
123  * task->runnable.userdata = task;
124  * vlc_executor_Submit(executor, &task->runnable);
125  * }
126  * \endcode
127  *
128  * A runnable instance is intended to be submitted at most once. The caller is
129  * expected to allocate a new task structure (embedding the runnable) for every
130  * submission.
131  *
132  * More precisely, it is incorrect to submit a runnable already submitted that
133  * is still in the pending queue (i.e. not canceled or started). This is due to
134  * the intrusive linked list of runnables.
135  *
136  * It is strongly discouraged to submit a runnable that is currently running on
137  * the executor (unless you are prepared for the run() callback to be run
138  * several times in parallel).
139  *
140  * For simplicity, it is discouraged to submit a runnable previously submitted.
141  *
142  * \param executor the executor
143  * \param runnable the task to run
144  */
145 VLC_API void
146 vlc_executor_Submit(vlc_executor_t *executor, struct vlc_runnable *runnable);
147 
148 /**
149  * Cancel a runnable previously submitted.
150  *
151  * If this runnable is still queued (i.e. it has not be run yet), then dequeue
152  * it so that it will never be run, and return true.
153  *
154  * Otherwise, this runnable has already been taken by an executor thread (it is
155  * still running or is complete). In that case, do nothing, and return false.
156  *
157  * This is an error to pass a runnable not submitted to this executor (the
158  * result is undefined in that case).
159  *
160  * Note that the runnable instance is owned by the caller, so the executor will
161  * never attempt to free it.
162  *
163  * \param executor the executor
164  * \param runnable the task to cancel
165  * \retval true if the runnable has been canceled before execution
166  * \retval false if the runnable has not been canceled
167  */
168 VLC_API bool
169 vlc_executor_Cancel(vlc_executor_t *executor, struct vlc_runnable *runnable);
170 
171 /**
172  * Wait until all submitted tasks are completed or canceled.
173  *
174  * \param executor the executor
175  */
176 VLC_API void
178 
179 # ifdef __cplusplus
180 }
181 # endif
182 
183  #endif
vlc_runnable::userdata
void * userdata
Userdata passed back to run().
Definition: vlc_executor.h:60
VLC_API
#define VLC_API
Definition: fourcc_gen.c:31
vlc_executor_Delete
VLC_EXPORT void vlc_executor_Delete(vlc_executor_t *executor)
Delete an executor.
Definition: executor.c:256
vlc_executor_WaitIdle
VLC_EXPORT void vlc_executor_WaitIdle(vlc_executor_t *executor)
Wait until all submitted tasks are completed or canceled.
Definition: executor.c:247
vlc_common.h
vlc_executor_New
VLC_EXPORT vlc_executor_t * vlc_executor_New(unsigned max_threads)
Create a new executor.
Definition: executor.c:173
vlc_executor
The executor (also vlc_executor_t, exposed as opaque type in the public header).
Definition: executor.c:55
vlc_executor_Submit
VLC_EXPORT void vlc_executor_Submit(vlc_executor_t *executor, struct vlc_runnable *runnable)
Submit a runnable for execution.
Definition: executor.c:206
vlc_list
Doubly-linked list node.
Definition: vlc_list.h:43
vlc_runnable
A Runnable encapsulates a task to be run from an executor thread.
Definition: vlc_executor.h:38
vlc_runnable::run
void(* run)(void *userdata)
This function is to be executed by a vlc_executor_t.
Definition: vlc_executor.h:55
vlc_list.h
vlc_runnable::node
struct vlc_list node
Definition: vlc_executor.h:63
vlc_executor_Cancel
VLC_EXPORT bool vlc_executor_Cancel(vlc_executor_t *executor, struct vlc_runnable *runnable)
Cancel a runnable previously submitted.
Definition: executor.c:223