src/util/work_queue_types.h

   1 /*
   2  * Copyright 2008-2010, Sine Nomine Associates and others.
   3  * All Rights Reserved.
   4  *
   5  * This software has been released under the terms of the IBM Public
   6  * License.  For details, see the LICENSE file in the top-level source
   7  * directory or online at http://www.openafs.org/dl/license10.html
   8  */
   9
  10 #ifndef AFS_UTIL_WORK_QUEUE_TYPES_H
  11 #define AFS_UTIL_WORK_QUEUE_TYPES_H 1
  12
  13
  14 /**
  15  *  public type definitions for work_queue.
  16  */
  17
  18 /* forward declare opaque types */
  19 struct afs_work_queue_node;
  20 struct afs_work_queue;
  21
  22 /**
  23  * options for creating a struct afs_work_queue.
  24  *
  25  * @see afs_wq_create
  26  */
  27 struct afs_work_queue_opts {
  28     unsigned int pend_hithresh; /**< maximum number of pending work nodes that
  29                                  *   can be in the work queue before
  30                                  *   non-forcing callers of afs_wq_add
  31                                  *   will block */
  32     unsigned int pend_lothresh; /**< when the number of pending work nodes
  33                                  *   falls below this number, any blocked
  34                                  *   callers of afs_wq_add are woken
  35                                  *   back up */
  36 };
  37
  38 /**
  39  * options to afs_wq_add.
  40  *
  41  * @see afs_wq_add
  42  */
  43 struct afs_work_queue_add_opts {
  44     int donate; /**< 1 to donate the caller's reference of the work node to
  45                  *   the queue, 0 to add a reference for the queue */
  46     int block;  /**< 1 to block if the queue is 'full', 0 to return
  47                  *   immediately with an error if the queue is full. Ignored
  48                  *   when 'force' is set */
  49     int force;  /**< 1 to force the node to be added to the queue, even if the
  50                  *   queue is at or beyond the pend_hithresh quota, 0 to block
  51                  *   or return an error according to the 'block' option */
  52 };
  53
  54 /**
  55  * work_queue callback function.
  56  *
  57  * @param[in] queue        pointer to struct afs_work_queue
  58  * @param[in] node         pointer to struct afs_work_queue_node
  59  * @param[in] queue_rock   opaque pointer associated with this work queue
  60  * @param[in] node_rock    opaque pointer associated with this work element
  61  * @param[in] caller_rock  opaque pointer passed in by caller of afs_wq_do()
  62  *
  63  * @return operation status
  64  *    @retval 0 success
  65  *    @retval AFS_WQ_ERROR callback suffered fatal error;
  66  *                              propagate to caller immediately.
  67  *    @retval AFS_WQ_ERROR_RECOVERABLE callback suffered a non-fatal error.
  68  *    @retval AFS_WQ_ERROR_RESCHEDULE callback requested to be scheduled
  69  *                                         again; for example it may have
  70  *                                         changed its dependencies.
  71  */
  72 typedef int afs_wq_callback_func_t(struct afs_work_queue * queue,
  73                                    struct afs_work_queue_node * node,
  74                                    void * queue_rock,
  75                                    void * node_rock,
  76                                    void * caller_rock);
  77
  78 /**
  79  * node rock destructor function.
  80  *
  81  * This function is called when the associated afs_work_queue_node is freed.
  82  * It should free any resources associated with the rock.
  83  *
  84  * @param[in] node_rock  rock given to the node's callback function
  85  */
  86 typedef void afs_wq_callback_dtor_t(void *node_rock);
  87
  88 #endif /* AFS_UTIL_WORK_QUEUE_TYPES_H */