"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/isc/include/isc/taskpool.h" (7 Sep 2020, 3708 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "taskpool.h" see the Fossies "Dox" file reference documentation.

    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 http://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 
   13 #ifndef ISC_TASKPOOL_H
   14 #define ISC_TASKPOOL_H 1
   15 
   16 /*****
   17  ***** Module Info
   18  *****/
   19 
   20 /*! \file isc/taskpool.h
   21  * \brief A task pool is a mechanism for sharing a small number of tasks
   22  * among a large number of objects such that each object is
   23  * assigned a unique task, but each task may be shared by several
   24  * objects.
   25  *
   26  * Task pools are used to let objects that can exist in large
   27  * numbers (e.g., zones) use tasks for synchronization without
   28  * the memory overhead and unfair scheduling competition that
   29  * could result from creating a separate task for each object.
   30  */
   31 
   32 
   33 /***
   34  *** Imports.
   35  ***/
   36 
   37 #include <stdbool.h>
   38 
   39 #include <isc/lang.h>
   40 #include <isc/task.h>
   41 
   42 ISC_LANG_BEGINDECLS
   43 
   44 /*****
   45  ***** Types.
   46  *****/
   47 
   48 typedef struct isc_taskpool isc_taskpool_t;
   49 
   50 /*****
   51  ***** Functions.
   52  *****/
   53 
   54 isc_result_t
   55 isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx,
   56             unsigned int ntasks, unsigned int quantum,
   57             isc_taskpool_t **poolp);
   58 /*%<
   59  * Create a task pool of "ntasks" tasks, each with quantum
   60  * "quantum".
   61  *
   62  * Requires:
   63  *
   64  *\li   'tmgr' is a valid task manager.
   65  *
   66  *\li   'mctx' is a valid memory context.
   67  *
   68  *\li   poolp != NULL && *poolp == NULL
   69  *
   70  * Ensures:
   71  *
   72  *\li   On success, '*taskp' points to the new task pool.
   73  *
   74  * Returns:
   75  *
   76  *\li   #ISC_R_SUCCESS
   77  *\li   #ISC_R_NOMEMORY
   78  *\li   #ISC_R_UNEXPECTED
   79  */
   80 
   81 void
   82 isc_taskpool_gettask(isc_taskpool_t *pool, isc_task_t **targetp);
   83 /*%<
   84  * Attach to a task from the pool.  Currently the next task is chosen
   85  * from the pool at random.  (This may be changed in the future to
   86  * something that guaratees balance.)
   87  */
   88 
   89 int
   90 isc_taskpool_size(isc_taskpool_t *pool);
   91 /*%<
   92  * Returns the number of tasks in the task pool 'pool'.
   93  */
   94 
   95 isc_result_t
   96 isc_taskpool_expand(isc_taskpool_t **sourcep, unsigned int size,
   97                     isc_taskpool_t **targetp);
   98 
   99 /*%<
  100  * If 'size' is larger than the number of tasks in the pool pointed to by
  101  * 'sourcep', then a new taskpool of size 'size' is allocated, the existing
  102  * tasks from are moved into it, additional tasks are created to bring the
  103  * total number up to 'size', and the resulting pool is attached to
  104  * 'targetp'.
  105  *
  106  * If 'size' is less than or equal to the tasks in pool 'source', then
  107  * 'sourcep' is attached to 'targetp' without any other action being taken.
  108  *
  109  * In either case, 'sourcep' is detached.
  110  *
  111  * Requires:
  112  *
  113  * \li  'sourcep' is not NULL and '*source' is not NULL
  114  * \li  'targetp' is not NULL and '*source' is NULL
  115  *
  116  * Ensures:
  117  *
  118  * \li  On success, '*targetp' points to a valid task pool.
  119  * \li  On success, '*sourcep' points to NULL.
  120  *
  121  * Returns:
  122  *
  123  * \li  #ISC_R_SUCCESS
  124  * \li  #ISC_R_NOMEMORY
  125  */
  126 
  127 void
  128 isc_taskpool_destroy(isc_taskpool_t **poolp);
  129 /*%<
  130  * Destroy a task pool.  The tasks in the pool are detached but not
  131  * shut down.
  132  *
  133  * Requires:
  134  * \li  '*poolp' is a valid task pool.
  135  */
  136 
  137 void
  138 isc_taskpool_setprivilege(isc_taskpool_t *pool, bool priv);
  139 /*%<
  140  * Set the privilege flag on all tasks in 'pool' to 'priv'.  If 'priv' is
  141  * true, then when the task manager is set into privileged mode, only
  142  * tasks wihin this pool will be able to execute.  (Note:  It is important
  143  * to turn the pool tasks' privilege back off before the last task finishes
  144  * executing.)
  145  *
  146  * Requires:
  147  * \li  'pool' is a valid task pool.
  148  */
  149 
  150 ISC_LANG_ENDDECLS
  151 
  152 #endif /* ISC_TASKPOOL_H */