include/vlc_executor.h

   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  */
  71 VLC_API vlc_executor_t *
  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
  89 vlc_executor_Delete(vlc_executor_t *executor);
  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
 177 vlc_executor_WaitIdle(vlc_executor_t *executor);
 178
 179 # ifdef __cplusplus
 180 }
 181 # endif
 182
 183  #endif