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