1/* 2 * Copyright (C) 2004-2007 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: taskpool.h,v 1.15 2007/06/19 23:47:18 tbox Exp $ */ 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 47ISC_LANG_BEGINDECLS 48 49/***** 50 ***** Types. 51 *****/ 52 53typedef struct isc_taskpool isc_taskpool_t; 54 55/***** 56 ***** Functions. 57 *****/ 58 59isc_result_t 60isc_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 86void 87isc_taskpool_gettask(isc_taskpool_t *pool, unsigned int hash, 88 isc_task_t **targetp); 89/*%< 90 * Attach to the task corresponding to the hash value "hash". 91 */ 92 93void 94isc_taskpool_destroy(isc_taskpool_t **poolp); 95/*%< 96 * Destroy a task pool. The tasks in the pool are detached but not 97 * shut down. 98 * 99 * Requires: 100 * \li '*poolp' is a valid task pool. 101 */ 102 103ISC_LANG_ENDDECLS 104 105#endif /* ISC_TASKPOOL_H */ 106