source3/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
  48 /**
  49  * @brief Destroy a pthreadpool
  50  *
  51  * Destroy a pthreadpool. If jobs are still active, this returns
  52  * EBUSY.
  53  *
  54  * @param[in]   pool            The pool to destroy
  55  * @return                      success: 0, failure: errno
  56  */
  57 int pthreadpool_destroy(struct pthreadpool *pool);
  58
  59 /**
  60  * @brief Add a job to a pthreadpool
  61  *
  62  * This adds a job to a pthreadpool. The job can be identified by
  63  * job_id. This integer will be returned from
  64  * pthreadpool_finished_jobs() then the job is completed.
  65  *
  66  * @param[in]   pool            The pool to run the job on
  67  * @param[in]   job_id          A custom identifier
  68  * @param[in]   fn              The function to run asynchronously
  69  * @param[in]   private_data    Pointer passed to fn
  70  * @return                      success: 0, failure: errno
  71  */
  72 int pthreadpool_add_job(struct pthreadpool *pool, int job_id,
  73                         void (*fn)(void *private_data), void *private_data);
  74
  75 /**
  76  * @brief Get the signalling fd from a pthreadpool
  77  *
  78  * Completion of a job is indicated by readability of the fd returned
  79  * by pthreadpool_signal_fd().
  80  *
  81  * @param[in]   pool            The pool in question
  82  * @return                      The fd to listen on for readability
  83  */
  84 int pthreadpool_signal_fd(struct pthreadpool *pool);
  85
  86 /**
  87  * @brief Get the job_ids of finished jobs
  88  *
  89  * This blocks until a job has finished unless the fd returned by
  90  * pthreadpool_signal_fd() is readable.
  91  *
  92  * @param[in]   pool            The pool to query for finished jobs
  93  * @param[out]  jobids          The job_ids of the finished job
  94  * @param[int]  num_jobids      The job_ids array size
  95  * @return                      success: >=0, number of finished jobs
  96  *                              failure: -errno
  97  */
  98 int pthreadpool_finished_jobs(struct pthreadpool *pool, int *jobids,
  99                               unsigned num_jobids);
 100
 101 #endif