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 Get the max threads value of pthreadpool
  55  *
  56  * @note This can be 0 for strict sync processing.
  57  *
  58  * @param[in]   pool            The pool
  59  * @return                      number of possible threads
  60  */
  61 size_t pthreadpool_max_threads(struct pthreadpool *pool);
  62
  63 /**
  64  * @brief The number of queued jobs of pthreadpool
  65  *
  66  * This is the number of jobs added by pthreadpool_add_job(),
  67  * which are not yet processed by a thread.
  68  *
  69  * @param[in]   pool            The pool
  70  * @return                      The number of jobs
  71  */
  72 size_t pthreadpool_queued_jobs(struct pthreadpool *pool);
  73
  74 /**
  75  * @brief Stop a pthreadpool
  76  *
  77  * Stop a pthreadpool. If jobs are submitted, but not yet active in
  78  * a thread, they won't get executed. If a job has already been
  79  * submitted to a thread, the job function will continue running, and
  80  * the signal function might still be called.
  81  *
  82  * This allows a multi step shutdown using pthreadpool_stop(),
  83  * pthreadpool_cancel_job() and pthreadpool_destroy().
  84  *
  85  * @param[in]   pool            The pool to stop
  86  * @return                      success: 0, failure: errno
  87  *
  88  * @see pthreadpool_cancel_job()
  89  * @see pthreadpool_destroy()
  90  */
  91 int pthreadpool_stop(struct pthreadpool *pool);
  92
  93 /**
  94  * @brief Destroy a pthreadpool
  95  *
  96  * This basically implies pthreadpool_stop() if the pool
  97  * isn't already stopped.
  98  *
  99  * Destroy a pthreadpool. If jobs are submitted, but not yet active in
 100  * a thread, they won't get executed. If a job has already been
 101  * submitted to a thread, the job function will continue running, and
 102  * the signal function might still be called. The caller of
 103  * pthreadpool_init must make sure the required resources are still
 104  * around when the pool is destroyed with pending jobs.  The last
 105  * thread to exit will finally free() the pool memory.
 106  *
 107  * @param[in]   pool            The pool to destroy
 108  * @return                      success: 0, failure: errno
 109  *
 110  * @see pthreadpool_stop()
 111  */
 112 int pthreadpool_destroy(struct pthreadpool *pool);
 113
 114 /**
 115  * @brief Add a job to a pthreadpool
 116  *
 117  * This adds a job to a pthreadpool. The job can be identified by
 118  * job_id. This integer will be passed to signal_fn() when the
 119  * job is completed.
 120  *
 121  * @param[in]   pool            The pool to run the job on
 122  * @param[in]   job_id          A custom identifier
 123  * @param[in]   fn              The function to run asynchronously
 124  * @param[in]   private_data    Pointer passed to fn
 125  * @return                      success: 0, failure: errno
 126  */
 127 int pthreadpool_add_job(struct pthreadpool *pool, int job_id,
 128                         void (*fn)(void *private_data), void *private_data);
 129
 130 /**
 131  * @brief Try to cancel a job in a pthreadpool
 132  *
 133  * This tries to cancel a job in a pthreadpool. The same
 134  * arguments, which were given to pthreadpool_add_job()
 135  * needs to be passed.
 136  *
 137  * The combination of id, fn, private_data might not be unique.
 138  * So the function tries to cancel as much matching jobs as possible.
 139  * Note once a job is scheduled in a thread it's to late to
 140  * cancel it.
 141  *
 142  * Canceled jobs that weren't started yet won't be reported via a
 143  * pool's signal_fn.
 144  *
 145  * @param[in]   pool            The pool to run the job on
 146  * @param[in]   job_id          A custom identifier
 147  * @param[in]   fn              The function to run asynchronously
 148  * @param[in]   private_data    Pointer passed to fn
 149  * @return                      The number of canceled jobs
 150  *
 151  * @see pthreadpool_add_job()
 152  * @see pthreadpool_stop()
 153  * @see pthreadpool_destroy()
 154  */
 155 size_t pthreadpool_cancel_job(struct pthreadpool *pool, int job_id,
 156                               void (*fn)(void *private_data), void *private_data);
 157
 158 #endif