third_party/libwebp/utils/thread.h

   1 // Copyright 2011 Google Inc. All Rights Reserved.
   2 //
   3 // Use of this source code is governed by a BSD-style license
   4 // that can be found in the COPYING file in the root of the source
   5 // tree. An additional intellectual property rights grant can be found
   6 // in the file PATENTS. All contributing project authors may
   7 // be found in the AUTHORS file in the root of the source tree.
   8 // -----------------------------------------------------------------------------
   9 //
  10 // Multi-threaded worker
  11 //
  12 // Author: Skal (pascal.massimino@gmail.com)
  13
  14 #ifndef WEBP_UTILS_THREAD_H_
  15 #define WEBP_UTILS_THREAD_H_
  16
  17 #ifdef HAVE_CONFIG_H
  18 #include "../webp/config.h"
  19 #endif
  20
  21 #include "../webp/types.h"
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 // State of the worker thread object
  28 typedef enum {
  29   NOT_OK = 0,   // object is unusable
  30   OK,           // ready to work
  31   WORK          // busy finishing the current task
  32 } WebPWorkerStatus;
  33
  34 // Function to be called by the worker thread. Takes two opaque pointers as
  35 // arguments (data1 and data2), and should return false in case of error.
  36 typedef int (*WebPWorkerHook)(void*, void*);
  37
  38 // Platform-dependent implementation details for the worker.
  39 typedef struct WebPWorkerImpl WebPWorkerImpl;
  40
  41 // Synchronization object used to launch job in the worker thread
  42 typedef struct {
  43   WebPWorkerImpl* impl_;
  44   WebPWorkerStatus status_;
  45   WebPWorkerHook hook;    // hook to call
  46   void* data1;            // first argument passed to 'hook'
  47   void* data2;            // second argument passed to 'hook'
  48   int had_error;          // return value of the last call to 'hook'
  49 } WebPWorker;
  50
  51 // The interface for all thread-worker related functions. All these functions
  52 // must be implemented.
  53 typedef struct {
  54   // Must be called first, before any other method.
  55   void (*Init)(WebPWorker* const worker);
  56   // Must be called to initialize the object and spawn the thread. Re-entrant.
  57   // Will potentially launch the thread. Returns false in case of error.
  58   int (*Reset)(WebPWorker* const worker);
  59   // Makes sure the previous work is finished. Returns true if worker->had_error
  60   // was not set and no error condition was triggered by the working thread.
  61   int (*Sync)(WebPWorker* const worker);
  62   // Triggers the thread to call hook() with data1 and data2 arguments. These
  63   // hook/data1/data2 values can be changed at any time before calling this
  64   // function, but not be changed afterward until the next call to Sync().
  65   void (*Launch)(WebPWorker* const worker);
  66   // This function is similar to Launch() except that it calls the
  67   // hook directly instead of using a thread. Convenient to bypass the thread
  68   // mechanism while still using the WebPWorker structs. Sync() must
  69   // still be called afterward (for error reporting).
  70   void (*Execute)(WebPWorker* const worker);
  71   // Kill the thread and terminate the object. To use the object again, one
  72   // must call Reset() again.
  73   void (*End)(WebPWorker* const worker);
  74 } WebPWorkerInterface;
  75
  76 // Install a new set of threading functions, overriding the defaults. This
  77 // should be done before any workers are started, i.e., before any encoding or
  78 // decoding takes place. The contents of the interface struct are copied, it
  79 // is safe to free the corresponding memory after this call. This function is
  80 // not thread-safe. Return false in case of invalid pointer or methods.
  81 WEBP_EXTERN(int) WebPSetWorkerInterface(
  82     const WebPWorkerInterface* const interface);
  83
  84 // Retrieve the currently set thread worker interface.
  85 WEBP_EXTERN(const WebPWorkerInterface*) WebPGetWorkerInterface(void);
  86
  87 //------------------------------------------------------------------------------
  88
  89 #ifdef __cplusplus
  90 }    // extern "C"
  91 #endif
  92
  93 #endif  /* WEBP_UTILS_THREAD_H_ */