1 /*
2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3  *
4  * This Source Code Form is subject to the terms of the Mozilla Public
5  * License, v. 2.0. If a copy of the MPL was not distributed with this
6  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
7  *
8  * See the COPYRIGHT file distributed with this work for additional
9  * information regarding copyright ownership.
10  */
11 
12 #ifndef ISC_TASKPOOL_H
13 #define ISC_TASKPOOL_H 1
14 
15 /*****
16 ***** Module Info
17 *****/
18 
19 /*! \file isc/taskpool.h
20  * \brief A task pool is a mechanism for sharing a small number of tasks
21  * among a large number of objects such that each object is
22  * assigned a unique task, but each task may be shared by several
23  * objects.
24  *
25  * Task pools are used to let objects that can exist in large
26  * numbers (e.g., zones) use tasks for synchronization without
27  * the memory overhead and unfair scheduling competition that
28  * could result from creating a separate task for each object.
29  */
30 
31 /***
32  *** Imports.
33  ***/
34 
35 #include <stdbool.h>
36 
37 #include <isc/lang.h>
38 #include <isc/task.h>
39 
40 ISC_LANG_BEGINDECLS
41 
42 /*****
43 ***** Types.
44 *****/
45 
46 typedef struct isc_taskpool isc_taskpool_t;
47 
48 /*****
49 ***** Functions.
50 *****/
51 
52 isc_result_t
53 isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx, unsigned int ntasks,
54 		    unsigned int quantum, bool priv, isc_taskpool_t **poolp);
55 /*%<
56  * Create a task pool of "ntasks" tasks, each with quantum
57  * "quantum".
58  *
59  * Requires:
60  *
61  *\li	'tmgr' is a valid task manager.
62  *
63  *\li	'mctx' is a valid memory context.
64  *
65  *\li	poolp != NULL && *poolp == NULL
66  *
67  * Ensures:
68  *
69  *\li	On success, '*taskp' points to the new task pool.
70  *
71  * Returns:
72  *
73  *\li	#ISC_R_SUCCESS
74  *\li	#ISC_R_NOMEMORY
75  *\li	#ISC_R_UNEXPECTED
76  */
77 
78 void
79 isc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp);
80 /*%<
81  * Attach to a task from the pool.  Currently the next task is chosen
82  * from the pool at random.  (This may be changed in the future to
83  * something that guaratees balance.)
84  */
85 
86 int
87 isc_taskpool_size(isc_taskpool_t *pool);
88 /*%<
89  * Returns the number of tasks in the task pool 'pool'.
90  */
91 
92 isc_result_t
93 isc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size, bool priv,
94 		    isc_taskpool_t **targetp);
95 
96 /*%<
97  * If 'size' is larger than the number of tasks in the pool pointed to by
98  * 'sourcep', then a new taskpool of size 'size' is allocated, the existing
99  * tasks from are moved into it, additional tasks are created to bring the
100  * total number up to 'size', and the resulting pool is attached to
101  * 'targetp'.
102  *
103  * If 'size' is less than or equal to the tasks in pool 'source', then
104  * 'sourcep' is attached to 'targetp' without any other action being taken.
105  *
106  * In either case, 'sourcep' is detached.
107  *
108  * Requires:
109  *
110  * \li	'sourcep' is not NULL and '*source' is not NULL
111  * \li	'targetp' is not NULL and '*source' is NULL
112  *
113  * Ensures:
114  *
115  * \li	On success, '*targetp' points to a valid task pool.
116  * \li	On success, '*sourcep' points to NULL.
117  *
118  * Returns:
119  *
120  * \li	#ISC_R_SUCCESS
121  * \li	#ISC_R_NOMEMORY
122  */
123 
124 void
125 isc_taskpool_destroy(isc_taskpool_t **poolp);
126 /*%<
127  * Destroy a task pool.  The tasks in the pool are detached but not
128  * shut down.
129  *
130  * Requires:
131  * \li	'*poolp' is a valid task pool.
132  */
133 
134 ISC_LANG_ENDDECLS
135 
136 #endif /* ISC_TASKPOOL_H */
137