third_party/aom/aom_util/aom_thread.h

   1 /*
   2  * Copyright (c) 2016, Alliance for Open Media. All rights reserved
   3  *
   4  * This source code is subject to the terms of the BSD 2 Clause License and
   5  * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
   6  * was not distributed with this source code in the LICENSE file, you can
   7  * obtain it at www.aomedia.org/license/software. If the Alliance for Open
   8  * Media Patent License 1.0 was not distributed with this source code in the
   9  * PATENTS file, you can obtain it at www.aomedia.org/license/patent.
  10  */
  11 //
  12 // Multi-threaded worker
  13 //
  14 // Original source:
  15 //  https://chromium.googlesource.com/webm/libwebp
  16
  17 #ifndef AOM_AOM_UTIL_AOM_THREAD_H_
  18 #define AOM_AOM_UTIL_AOM_THREAD_H_
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 // State of the worker thread object
  25 typedef enum {
  26   AVX_WORKER_STATUS_NOT_OK = 0,  // object is unusable
  27   AVX_WORKER_STATUS_OK,          // ready to work
  28   AVX_WORKER_STATUS_WORKING      // busy finishing the current task
  29 } AVxWorkerStatus;
  30
  31 // Function to be called by the worker thread. Takes two opaque pointers as
  32 // arguments (data1 and data2). Should return true on success and return false
  33 // in case of error.
  34 typedef int (*AVxWorkerHook)(void *, void *);
  35
  36 // Platform-dependent implementation details for the worker.
  37 typedef struct AVxWorkerImpl AVxWorkerImpl;
  38
  39 // Synchronization object used to launch job in the worker thread
  40 typedef struct {
  41   AVxWorkerImpl *impl_;
  42   AVxWorkerStatus status_;
  43   // Thread name for the debugger. If not NULL, must point to a string that
  44   // outlives the worker thread. For portability, use a name <= 15 characters
  45   // long (not including the terminating NUL character).
  46   const char *thread_name;
  47   AVxWorkerHook hook;  // hook to call
  48   void *data1;         // first argument passed to 'hook'
  49   void *data2;         // second argument passed to 'hook'
  50   int had_error;       // true if a call to 'hook' returned false
  51 } AVxWorker;
  52
  53 // The interface for all thread-worker related functions. All these functions
  54 // must be implemented.
  55 typedef struct {
  56   // Must be called first, before any other method.
  57   void (*init)(AVxWorker *const worker);
  58   // Must be called to initialize the object and spawn the thread. Re-entrant.
  59   // Will potentially launch the thread. Returns false in case of error.
  60   int (*reset)(AVxWorker *const worker);
  61   // Makes sure the previous work is finished. Returns true if worker->had_error
  62   // was not set and no error condition was triggered by the working thread.
  63   int (*sync)(AVxWorker *const worker);
  64   // Triggers the thread to call hook() with data1 and data2 arguments. These
  65   // hook/data1/data2 values can be changed at any time before calling this
  66   // function, but not be changed afterward until the next call to Sync().
  67   void (*launch)(AVxWorker *const worker);
  68   // This function is similar to launch() except that it calls the
  69   // hook directly instead of using a thread. Convenient to bypass the thread
  70   // mechanism while still using the AVxWorker structs. sync() must
  71   // still be called afterward (for error reporting).
  72   void (*execute)(AVxWorker *const worker);
  73   // Kill the thread and terminate the object. To use the object again, one
  74   // must call reset() again.
  75   void (*end)(AVxWorker *const worker);
  76 } AVxWorkerInterface;
  77
  78 // Install a new set of threading functions, overriding the defaults. This
  79 // should be done before any workers are started, i.e., before any encoding or
  80 // decoding takes place. The contents of the interface struct are copied, it
  81 // is safe to free the corresponding memory after this call. This function is
  82 // not thread-safe. Return false in case of invalid pointer or methods.
  83 int aom_set_worker_interface(const AVxWorkerInterface *const winterface);
  84
  85 // Retrieve the currently set thread worker interface.
  86 const AVxWorkerInterface *aom_get_worker_interface(void);
  87
  88 //------------------------------------------------------------------------------
  89
  90 #ifdef __cplusplus
  91 }  // extern "C"
  92 #endif
  93
  94 #endif  // AOM_AOM_UTIL_AOM_THREAD_H_