taskpool.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2004-2007, 2011, 2012  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 1999-2001  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 /* $Id$ */
00019 
00020 #ifndef ISC_TASKPOOL_H
00021 #define ISC_TASKPOOL_H 1
00022 
00023 /*****
00024  ***** Module Info
00025  *****/
00026 
00027 /*! \file isc/taskpool.h
00028  * \brief A task pool is a mechanism for sharing a small number of tasks
00029  * among a large number of objects such that each object is
00030  * assigned a unique task, but each task may be shared by several
00031  * objects.
00032  *
00033  * Task pools are used to let objects that can exist in large
00034  * numbers (e.g., zones) use tasks for synchronization without
00035  * the memory overhead and unfair scheduling competition that
00036  * could result from creating a separate task for each object.
00037  */
00038 
00039 
00040 /***
00041  *** Imports.
00042  ***/
00043 
00044 #include <isc/lang.h>
00045 #include <isc/task.h>
00046 
00047 ISC_LANG_BEGINDECLS
00048 
00049 /*****
00050  ***** Types.
00051  *****/
00052 
00053 typedef struct isc_taskpool isc_taskpool_t;
00054 
00055 /*****
00056  ***** Functions.
00057  *****/
00058 
00059 isc_result_t
00060 isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx,
00061                     unsigned int ntasks, unsigned int quantum,
00062                     isc_taskpool_t **poolp);
00063 /*%<
00064  * Create a task pool of "ntasks" tasks, each with quantum
00065  * "quantum".
00066  *
00067  * Requires:
00068  *
00069  *\li   'tmgr' is a valid task manager.
00070  *
00071  *\li   'mctx' is a valid memory context.
00072  *
00073  *\li   poolp != NULL && *poolp == NULL
00074  *
00075  * Ensures:
00076  *
00077  *\li   On success, '*taskp' points to the new task pool.
00078  *
00079  * Returns:
00080  *
00081  *\li   #ISC_R_SUCCESS
00082  *\li   #ISC_R_NOMEMORY
00083  *\li   #ISC_R_UNEXPECTED
00084  */
00085 
00086 void
00087 isc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp);
00088 /*%<
00089  * Attach to a task from the pool.  Currently the next task is chosen
00090  * from the pool at random.  (This may be changed in the future to
00091  * something that guaratees balance.)
00092  */
00093 
00094 int
00095 isc_taskpool_size(isc_taskpool_t *pool);
00096 /*%<
00097  * Returns the number of tasks in the task pool 'pool'.
00098  */
00099 
00100 isc_result_t
00101 isc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size,
00102                                         isc_taskpool_t **targetp);
00103 
00104 /*%<
00105  * If 'size' is larger than the number of tasks in the pool pointed to by
00106  * 'sourcep', then a new taskpool of size 'size' is allocated, the existing
00107  * tasks from are moved into it, additional tasks are created to bring the
00108  * total number up to 'size', and the resulting pool is attached to
00109  * 'targetp'.
00110  *
00111  * If 'size' is less than or equal to the tasks in pool 'source', then
00112  * 'sourcep' is attached to 'targetp' without any other action being taken.
00113  *
00114  * In either case, 'sourcep' is detached.
00115  *
00116  * Requires:
00117  *
00118  * \li  'sourcep' is not NULL and '*source' is not NULL
00119  * \li  'targetp' is not NULL and '*source' is NULL
00120  *
00121  * Ensures:
00122  *
00123  * \li  On success, '*targetp' points to a valid task pool.
00124  * \li  On success, '*sourcep' points to NULL.
00125  *
00126  * Returns:
00127  *
00128  * \li  #ISC_R_SUCCESS
00129  * \li  #ISC_R_NOMEMORY
00130  */
00131 
00132 void
00133 isc_taskpool_destroy(isc_taskpool_t **poolp);
00134 /*%<
00135  * Destroy a task pool.  The tasks in the pool are detached but not
00136  * shut down.
00137  *
00138  * Requires:
00139  * \li  '*poolp' is a valid task pool.
00140  */
00141 
00142 void
00143 isc_taskpool_setprivilege(isc_taskpool_t *pool, isc_boolean_t priv);
00144 /*%<
00145  * Set the privilege flag on all tasks in 'pool' to 'priv'.  If 'priv' is
00146  * true, then when the task manager is set into privileged mode, only
00147  * tasks wihin this pool will be able to execute.  (Note:  It is important
00148  * to turn the pool tasks' privilege back off before the last task finishes
00149  * executing.)
00150  *
00151  * Requires:
00152  * \li  'pool' is a valid task pool.
00153  */
00154 
00155 ISC_LANG_ENDDECLS
00156 
00157 #endif /* ISC_TASKPOOL_H */

Generated on Tue Apr 28 17:41:04 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha