1258945Sroberto/* 2280849Scy * Copyright (C) 2004-2007, 2011, 2012 Internet Systems Consortium, Inc. ("ISC") 3258945Sroberto * Copyright (C) 1999-2001 Internet Software Consortium. 4258945Sroberto * 5258945Sroberto * Permission to use, copy, modify, and/or distribute this software for any 6258945Sroberto * purpose with or without fee is hereby granted, provided that the above 7258945Sroberto * copyright notice and this permission notice appear in all copies. 8258945Sroberto * 9258945Sroberto * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10258945Sroberto * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11258945Sroberto * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12258945Sroberto * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13258945Sroberto * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14258945Sroberto * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15258945Sroberto * PERFORMANCE OF THIS SOFTWARE. 16258945Sroberto */ 17258945Sroberto 18280849Scy/* $Id$ */ 19258945Sroberto 20258945Sroberto#ifndef ISC_TASKPOOL_H 21258945Sroberto#define ISC_TASKPOOL_H 1 22258945Sroberto 23258945Sroberto/***** 24258945Sroberto ***** Module Info 25258945Sroberto *****/ 26258945Sroberto 27258945Sroberto/*! \file isc/taskpool.h 28258945Sroberto * \brief A task pool is a mechanism for sharing a small number of tasks 29258945Sroberto * among a large number of objects such that each object is 30258945Sroberto * assigned a unique task, but each task may be shared by several 31258945Sroberto * objects. 32258945Sroberto * 33258945Sroberto * Task pools are used to let objects that can exist in large 34258945Sroberto * numbers (e.g., zones) use tasks for synchronization without 35258945Sroberto * the memory overhead and unfair scheduling competition that 36258945Sroberto * could result from creating a separate task for each object. 37258945Sroberto */ 38258945Sroberto 39258945Sroberto 40258945Sroberto/*** 41258945Sroberto *** Imports. 42258945Sroberto ***/ 43258945Sroberto 44258945Sroberto#include <isc/lang.h> 45258945Sroberto#include <isc/task.h> 46258945Sroberto 47258945SrobertoISC_LANG_BEGINDECLS 48258945Sroberto 49258945Sroberto/***** 50258945Sroberto ***** Types. 51258945Sroberto *****/ 52258945Sroberto 53258945Srobertotypedef struct isc_taskpool isc_taskpool_t; 54258945Sroberto 55258945Sroberto/***** 56258945Sroberto ***** Functions. 57258945Sroberto *****/ 58258945Sroberto 59258945Srobertoisc_result_t 60258945Srobertoisc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx, 61258945Sroberto unsigned int ntasks, unsigned int quantum, 62258945Sroberto isc_taskpool_t **poolp); 63258945Sroberto/*%< 64258945Sroberto * Create a task pool of "ntasks" tasks, each with quantum 65258945Sroberto * "quantum". 66258945Sroberto * 67258945Sroberto * Requires: 68258945Sroberto * 69258945Sroberto *\li 'tmgr' is a valid task manager. 70258945Sroberto * 71258945Sroberto *\li 'mctx' is a valid memory context. 72258945Sroberto * 73258945Sroberto *\li poolp != NULL && *poolp == NULL 74258945Sroberto * 75258945Sroberto * Ensures: 76258945Sroberto * 77258945Sroberto *\li On success, '*taskp' points to the new task pool. 78258945Sroberto * 79258945Sroberto * Returns: 80258945Sroberto * 81258945Sroberto *\li #ISC_R_SUCCESS 82258945Sroberto *\li #ISC_R_NOMEMORY 83258945Sroberto *\li #ISC_R_UNEXPECTED 84258945Sroberto */ 85258945Sroberto 86280849Scyvoid 87280849Scyisc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp); 88258945Sroberto/*%< 89280849Scy * Attach to a task from the pool. Currently the next task is chosen 90280849Scy * from the pool at random. (This may be changed in the future to 91280849Scy * something that guaratees balance.) 92258945Sroberto */ 93258945Sroberto 94280849Scyint 95280849Scyisc_taskpool_size(isc_taskpool_t *pool); 96280849Scy/*%< 97280849Scy * Returns the number of tasks in the task pool 'pool'. 98280849Scy */ 99280849Scy 100280849Scyisc_result_t 101280849Scyisc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size, 102280849Scy isc_taskpool_t **targetp); 103280849Scy 104280849Scy/*%< 105280849Scy * If 'size' is larger than the number of tasks in the pool pointed to by 106280849Scy * 'sourcep', then a new taskpool of size 'size' is allocated, the existing 107280849Scy * tasks from are moved into it, additional tasks are created to bring the 108280849Scy * total number up to 'size', and the resulting pool is attached to 109280849Scy * 'targetp'. 110280849Scy * 111280849Scy * If 'size' is less than or equal to the tasks in pool 'source', then 112280849Scy * 'sourcep' is attached to 'targetp' without any other action being taken. 113280849Scy * 114280849Scy * In either case, 'sourcep' is detached. 115280849Scy * 116280849Scy * Requires: 117280849Scy * 118280849Scy * \li 'sourcep' is not NULL and '*source' is not NULL 119280849Scy * \li 'targetp' is not NULL and '*source' is NULL 120280849Scy * 121280849Scy * Ensures: 122280849Scy * 123280849Scy * \li On success, '*targetp' points to a valid task pool. 124280849Scy * \li On success, '*sourcep' points to NULL. 125280849Scy * 126280849Scy * Returns: 127280849Scy * 128280849Scy * \li #ISC_R_SUCCESS 129280849Scy * \li #ISC_R_NOMEMORY 130280849Scy */ 131280849Scy 132258945Srobertovoid 133258945Srobertoisc_taskpool_destroy(isc_taskpool_t **poolp); 134258945Sroberto/*%< 135258945Sroberto * Destroy a task pool. The tasks in the pool are detached but not 136258945Sroberto * shut down. 137258945Sroberto * 138258945Sroberto * Requires: 139258945Sroberto * \li '*poolp' is a valid task pool. 140258945Sroberto */ 141258945Sroberto 142280849Scyvoid 143280849Scyisc_taskpool_setprivilege(isc_taskpool_t *pool, isc_boolean_t priv); 144280849Scy/*%< 145280849Scy * Set the privilege flag on all tasks in 'pool' to 'priv'. If 'priv' is 146280849Scy * true, then when the task manager is set into privileged mode, only 147280849Scy * tasks wihin this pool will be able to execute. (Note: It is important 148280849Scy * to turn the pool tasks' privilege back off before the last task finishes 149280849Scy * executing.) 150280849Scy * 151280849Scy * Requires: 152280849Scy * \li 'pool' is a valid task pool. 153280849Scy */ 154280849Scy 155258945SrobertoISC_LANG_ENDDECLS 156258945Sroberto 157258945Sroberto#endif /* ISC_TASKPOOL_H */ 158