module/zstd/lib/common/pool.h

   1 /*
   2  * Copyright (c) 2016-2020, Yann Collet, Facebook, Inc.
   3  * All rights reserved.
   4  *
   5  * This source code is licensed under both the BSD-style license (found in the
   6  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
   7  * in the COPYING file in the root directory of this source tree).
   8  * You may select, at your option, one of the above-listed licenses.
   9  */
  10
  11 #ifndef POOL_H
  12 #define POOL_H
  13
  14 #if defined (__cplusplus)
  15 extern "C" {
  16 #endif
  17
  18
  19 #include <stddef.h>   /* size_t */
  20 #define ZSTD_STATIC_LINKING_ONLY   /* ZSTD_customMem */
  21 #include "../zstd.h"
  22
  23 typedef struct POOL_ctx_s POOL_ctx;
  24
  25 /*! POOL_create() :
  26  *  Create a thread pool with at most `numThreads` threads.
  27  * `numThreads` must be at least 1.
  28  *  The maximum number of queued jobs before blocking is `queueSize`.
  29  * @return : POOL_ctx pointer on success, else NULL.
  30 */
  31 POOL_ctx* POOL_create(size_t numThreads, size_t queueSize);
  32
  33 POOL_ctx* POOL_create_advanced(size_t numThreads, size_t queueSize,
  34                                ZSTD_customMem customMem);
  35
  36 /*! POOL_free() :
  37  *  Free a thread pool returned by POOL_create().
  38  */
  39 void POOL_free(POOL_ctx* ctx);
  40
  41 /*! POOL_resize() :
  42  *  Expands or shrinks pool's number of threads.
  43  *  This is more efficient than releasing + creating a new context,
  44  *  since it tries to preserve and re-use existing threads.
  45  * `numThreads` must be at least 1.
  46  * @return : 0 when resize was successful,
  47  *           !0 (typically 1) if there is an error.
  48  *    note : only numThreads can be resized, queueSize remains unchanged.
  49  */
  50 int POOL_resize(POOL_ctx* ctx, size_t numThreads);
  51
  52 /*! POOL_sizeof() :
  53  * @return threadpool memory usage
  54  *  note : compatible with NULL (returns 0 in this case)
  55  */
  56 size_t POOL_sizeof(POOL_ctx* ctx);
  57
  58 /*! POOL_function :
  59  *  The function type that can be added to a thread pool.
  60  */
  61 typedef void (*POOL_function)(void*);
  62
  63 /*! POOL_add() :
  64  *  Add the job `function(opaque)` to the thread pool. `ctx` must be valid.
  65  *  Possibly blocks until there is room in the queue.
  66  *  Note : The function may be executed asynchronously,
  67  *         therefore, `opaque` must live until function has been completed.
  68  */
  69 void POOL_add(POOL_ctx* ctx, POOL_function function, void* opaque);
  70
  71
  72 /*! POOL_tryAdd() :
  73  *  Add the job `function(opaque)` to thread pool _if_ a worker is available.
  74  *  Returns immediately even if not (does not block).
  75  * @return : 1 if successful, 0 if not.
  76  */
  77 int POOL_tryAdd(POOL_ctx* ctx, POOL_function function, void* opaque);
  78
  79
  80 #if defined (__cplusplus)
  81 }
  82 #endif
  83
  84 #endif