lib/pthreadpool/pthreadpool.h

   1 /*
   2  * Unix SMB/CIFS implementation.
   3  * threadpool implementation based on pthreads
   4  * Copyright (C) Volker Lendecke 2009,2011
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef __PTHREADPOOL_H__
  21 #define __PTHREADPOOL_H__
  22
  23 struct pthreadpool;
  24
  25 /**
  26  * @defgroup pthreadpool The pthreadpool API
  27  *
  28  * This API provides a way to run threadsafe functions in a helper
  29  * thread. It is initially intended to run getaddrinfo asynchronously.
  30  */
  31
  32
  33 /**
  34  * @brief Create a pthreadpool
  35  *
  36  * A struct pthreadpool is the basis for for running threads in the
  37  * background.
  38  *
  39  * @param[in]   max_threads     Maximum parallelism in this pool
  40  * @param[out]  presult         Pointer to the threadpool returned
  41  * @return                      success: 0, failure: errno
  42  *
  43  * max_threads=0 means unlimited parallelism. The caller has to take
  44  * care to not overload the system.
  45  */
  46 int pthreadpool_init(unsigned max_threads, struct pthreadpool **presult,
  47                      int (*signal_fn)(int jobid,
  48                                       void (*job_fn)(void *private_data),
  49                                       void *job_fn_private_data,
  50                                       void *private_data),
  51                      void *signal_fn_private_data);
  52
  53 /**
  54  * @brief Destroy a pthreadpool
  55  *
  56  * Destroy a pthreadpool. If jobs are submitted, but not yet active in
  57  * a thread, they won't get executed. If a job has already been
  58  * submitted to a thread, the job function will continue running, and
  59  * the signal function might still be called. The caller of
  60  * pthreadpool_init must make sure the required resources are still
  61  * around when the pool is destroyed with pending jobs.  The last
  62  * thread to exit will finally free() the pool memory.
  63  *
  64  * @param[in]   pool            The pool to destroy
  65  * @return                      success: 0, failure: errno
  66  */
  67 int pthreadpool_destroy(struct pthreadpool *pool);
  68
  69 /**
  70  * @brief Add a job to a pthreadpool
  71  *
  72  * This adds a job to a pthreadpool. The job can be identified by
  73  * job_id. This integer will be passed to signal_fn() when the
  74  * job is completed.
  75  *
  76  * @param[in]   pool            The pool to run the job on
  77  * @param[in]   job_id          A custom identifier
  78  * @param[in]   fn              The function to run asynchronously
  79  * @param[in]   private_data    Pointer passed to fn
  80  * @return                      success: 0, failure: errno
  81  */
  82 int pthreadpool_add_job(struct pthreadpool *pool, int job_id,
  83                         void (*fn)(void *private_data), void *private_data);
  84
  85 #endif