contrib/bind-9.3/lib/isc/include/isc/taskpool.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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: taskpool.h,v 1.8.206.1 2004/03/06 08:14:49 marka Exp $ */
  19
  20 #ifndef ISC_TASKPOOL_H
  21 #define ISC_TASKPOOL_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * Task Pool
  29  *
  30  * A task pool is a mechanism for sharing a small number of tasks
  31  * among a large number of objects such that each object is
  32  * assigned a unique task, but each task may be shared by several
  33  * objects.
  34  *
  35  * Task pools are used to let objects that can exist in large
  36  * numbers (e.g., zones) use tasks for synchronization without
  37  * the memory overhead and unfair scheduling competition that
  38  * could result from creating a separate task for each object.
  39  */
  40
  41
  42 /***
  43  *** Imports.
  44  ***/
  45
  46 #include <isc/lang.h>
  47 #include <isc/task.h>
  48
  49 ISC_LANG_BEGINDECLS
  50
  51 /*****
  52  ***** Types.
  53  *****/
  54
  55 typedef struct isc_taskpool isc_taskpool_t;
  56
  57 /*****
  58  ***** Functions.
  59  *****/
  60
  61 isc_result_t
  62 isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx,
  63                     unsigned int ntasks, unsigned int quantum,
  64                     isc_taskpool_t **poolp);
  65 /*
  66  * Create a task pool of "ntasks" tasks, each with quantum
  67  * "quantum".
  68  *
  69  * Requires:
  70  *
  71  *      'tmgr' is a valid task manager.
  72  *
  73  *      'mctx' is a valid memory context.
  74  *
  75  *      poolp != NULL && *poolp == NULL
  76  *
  77  * Ensures:
  78  *
  79  *      On success, '*taskp' points to the new task pool.
  80  *
  81  * Returns:
  82  *
  83  *      ISC_R_SUCCESS
  84  *      ISC_R_NOMEMORY
  85  *      ISC_R_UNEXPECTED
  86  */
  87
  88 void
  89 isc_taskpool_gettask(isc_taskpool_t *pool, unsigned int hash,
  90                           isc_task_t **targetp);
  91 /*
  92  * Attach to the task corresponding to the hash value "hash".
  93  */
  94
  95 void
  96 isc_taskpool_destroy(isc_taskpool_t **poolp);
  97 /*
  98  * Destroy a task pool.  The tasks in the pool are detached but not
  99  * shut down.
 100  *
 101  * Requires:
 102  *      '*poolp' is a valid task pool.
 103  */
 104
 105 ISC_LANG_ENDDECLS
 106
 107 #endif /* ISC_TASKPOOL_H */