Home | History | Annotate | Line # | Download | only in common 
      1 /*
      2  * Copyright (c) Meta Platforms, Inc. and affiliates.
      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 
     15 #include "zstd_deps.h"
     16 #define ZSTD_STATIC_LINKING_ONLY   /* ZSTD_customMem */
     17 #include "../zstd.h"
     18 
     19 typedef struct POOL_ctx_s POOL_ctx;
     20 
     21 /*! POOL_create() :
     22  *  Create a thread pool with at most `numThreads` threads.
     23  * `numThreads` must be at least 1.
     24  *  The maximum number of queued jobs before blocking is `queueSize`.
     25  * @return : POOL_ctx pointer on success, else NULL.
     26 */
     27 POOL_ctx* POOL_create(size_t numThreads, size_t queueSize);
     28 
     29 POOL_ctx* POOL_create_advanced(size_t numThreads, size_t queueSize,
     30                                ZSTD_customMem customMem);
     31 
     32 /*! POOL_free() :
     33  *  Free a thread pool returned by POOL_create().
     34  */
     35 void POOL_free(POOL_ctx* ctx);
     36 
     37 
     38 /*! POOL_joinJobs() :
     39  *  Waits for all queued jobs to finish executing.
     40  */
     41 void POOL_joinJobs(POOL_ctx* ctx);
     42 
     43 /*! POOL_resize() :
     44  *  Expands or shrinks pool's number of threads.
     45  *  This is more efficient than releasing + creating a new context,
     46  *  since it tries to preserve and reuse existing threads.
     47  * `numThreads` must be at least 1.
     48  * @return : 0 when resize was successful,
     49  *           !0 (typically 1) if there is an error.
     50  *    note : only numThreads can be resized, queueSize remains unchanged.
     51  */
     52 int POOL_resize(POOL_ctx* ctx, size_t numThreads);
     53 
     54 /*! POOL_sizeof() :
     55  * @return threadpool memory usage
     56  *  note : compatible with NULL (returns 0 in this case)
     57  */
     58 size_t POOL_sizeof(const POOL_ctx* ctx);
     59 
     60 /*! POOL_function :
     61  *  The function type that can be added to a thread pool.
     62  */
     63 typedef void (*POOL_function)(void*);
     64 
     65 /*! POOL_add() :
     66  *  Add the job `function(opaque)` to the thread pool. `ctx` must be valid.
     67  *  Possibly blocks until there is room in the queue.
     68  *  Note : The function may be executed asynchronously,
     69  *         therefore, `opaque` must live until function has been completed.
     70  */
     71 void POOL_add(POOL_ctx* ctx, POOL_function function, void* opaque);
     72 
     73 
     74 /*! POOL_tryAdd() :
     75  *  Add the job `function(opaque)` to thread pool _if_ a queue slot is available.
     76  *  Returns immediately even if not (does not block).
     77  * @return : 1 if successful, 0 if not.
     78  */
     79 int POOL_tryAdd(POOL_ctx* ctx, POOL_function function, void* opaque);
     80 
     81 #endif
     82