contrib/bind9/lib/isc/include/isc/taskpool.h

   1 /*
   2  * Copyright (C) 2004-2007, 2011, 2012  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id$ */
  19
  20 #ifndef ISC_TASKPOOL_H
  21 #define ISC_TASKPOOL_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file isc/taskpool.h
  28  * \brief A task pool is a mechanism for sharing a small number of tasks
  29  * among a large number of objects such that each object is
  30  * assigned a unique task, but each task may be shared by several
  31  * objects.
  32  *
  33  * Task pools are used to let objects that can exist in large
  34  * numbers (e.g., zones) use tasks for synchronization without
  35  * the memory overhead and unfair scheduling competition that
  36  * could result from creating a separate task for each object.
  37  */
  38
  39
  40 /***
  41  *** Imports.
  42  ***/
  43
  44 #include <isc/lang.h>
  45 #include <isc/task.h>
  46
  47 ISC_LANG_BEGINDECLS
  48
  49 /*****
  50  ***** Types.
  51  *****/
  52
  53 typedef struct isc_taskpool isc_taskpool_t;
  54
  55 /*****
  56  ***** Functions.
  57  *****/
  58
  59 isc_result_t
  60 isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx,
  61                     unsigned int ntasks, unsigned int quantum,
  62                     isc_taskpool_t **poolp);
  63 /*%<
  64  * Create a task pool of "ntasks" tasks, each with quantum
  65  * "quantum".
  66  *
  67  * Requires:
  68  *
  69  *\li   'tmgr' is a valid task manager.
  70  *
  71  *\li   'mctx' is a valid memory context.
  72  *
  73  *\li   poolp != NULL && *poolp == NULL
  74  *
  75  * Ensures:
  76  *
  77  *\li   On success, '*taskp' points to the new task pool.
  78  *
  79  * Returns:
  80  *
  81  *\li   #ISC_R_SUCCESS
  82  *\li   #ISC_R_NOMEMORY
  83  *\li   #ISC_R_UNEXPECTED
  84  */
  85
  86 void
  87 isc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp);
  88 /*%<
  89  * Attach to a task from the pool.  Currently the next task is chosen
  90  * from the pool at random.  (This may be changed in the future to
  91  * something that guaratees balance.)
  92  */
  93
  94 int
  95 isc_taskpool_size(isc_taskpool_t *pool);
  96 /*%<
  97  * Returns the number of tasks in the task pool 'pool'.
  98  */
  99
 100 isc_result_t
 101 isc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size,
 102                                         isc_taskpool_t **targetp);
 103
 104 /*%<
 105  * If 'size' is larger than the number of tasks in the pool pointed to by
 106  * 'sourcep', then a new taskpool of size 'size' is allocated, the existing
 107  * tasks from are moved into it, additional tasks are created to bring the
 108  * total number up to 'size', and the resulting pool is attached to
 109  * 'targetp'.
 110  *
 111  * If 'size' is less than or equal to the tasks in pool 'source', then
 112  * 'sourcep' is attached to 'targetp' without any other action being taken.
 113  *
 114  * In either case, 'sourcep' is detached.
 115  *
 116  * Requires:
 117  *
 118  * \li  'sourcep' is not NULL and '*source' is not NULL
 119  * \li  'targetp' is not NULL and '*source' is NULL
 120  *
 121  * Ensures:
 122  *
 123  * \li  On success, '*targetp' points to a valid task pool.
 124  * \li  On success, '*sourcep' points to NULL.
 125  *
 126  * Returns:
 127  *
 128  * \li  #ISC_R_SUCCESS
 129  * \li  #ISC_R_NOMEMORY
 130  */
 131
 132 void
 133 isc_taskpool_destroy(isc_taskpool_t **poolp);
 134 /*%<
 135  * Destroy a task pool.  The tasks in the pool are detached but not
 136  * shut down.
 137  *
 138  * Requires:
 139  * \li  '*poolp' is a valid task pool.
 140  */
 141
 142 ISC_LANG_ENDDECLS
 143
 144 #endif /* ISC_TASKPOOL_H */