lib/workqueue.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /*
   3  * Quagga Work Queues.
   4  *
   5  * Copyright (C) 2005 Sun Microsystems, Inc.
   6  */
   7
   8 #ifndef _QUAGGA_WORK_QUEUE_H
   9 #define _QUAGGA_WORK_QUEUE_H
  10
  11 #include "memory.h"
  12 #include "queue.h"
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 DECLARE_MTYPE(WORK_QUEUE);
  19
  20 /* Hold time for the initial schedule of a queue run, in  millisec */
  21 #define WORK_QUEUE_DEFAULT_HOLD 50
  22
  23 /* Retry for queue that is 'blocked' or 'retry later' */
  24 #define WORK_QUEUE_DEFAULT_RETRY 0
  25
  26 /* action value, for use by item processor and item error handlers */
  27 typedef enum {
  28         WQ_SUCCESS = 0,
  29         WQ_RETRY_NOW,     /* retry immediately */
  30         WQ_RETRY_LATER,   /* retry later, cease processing work queue */
  31         WQ_REQUEUE,       /* requeue item, continue processing work queue */
  32         WQ_QUEUE_BLOCKED, /* Queue cant be processed at this time.
  33                            * Similar to WQ_RETRY_LATER, but doesn't penalise
  34                            * the particular item.. */
  35 } wq_item_status;
  36
  37 /* A single work queue item, unsurprisingly */
  38 struct work_queue_item {
  39         STAILQ_ENTRY(work_queue_item) wq;
  40         void *data;      /* opaque data */
  41         unsigned short ran; /* # of times item has been run */
  42 };
  43
  44 #define WQ_UNPLUGGED    (1 << 0) /* available for draining */
  45
  46 struct work_queue {
  47         /* Everything but the specification struct is private
  48          * the following may be read
  49          */
  50         struct thread_master *master; /* thread master */
  51         struct thread *thread;  /* thread, if one is active */
  52         char *name;                   /* work queue name */
  53
  54         /* Specification for this work queue.
  55          * Public, must be set before use by caller. May be modified at will.
  56          */
  57         struct {
  58                 /* optional opaque user data, global to the queue. */
  59                 void *data;
  60
  61                 /* work function to process items with:
  62                  * First argument is the workqueue queue.
  63                  * Second argument is the item data
  64                  */
  65                 wq_item_status (*workfunc)(struct work_queue *, void *);
  66
  67                 /* callback to delete user specific item data */
  68                 void (*del_item_data)(struct work_queue *, void *);
  69
  70                 /* completion callback, called when queue is emptied, optional
  71                  */
  72                 void (*completion_func)(struct work_queue *);
  73
  74                 /* max number of retries to make for item that errors */
  75                 unsigned int max_retries;
  76
  77                 unsigned int hold; /* hold time for first run, in ms */
  78
  79                 unsigned long
  80                         yield; /* yield time in us for associated thread */
  81
  82                 uint32_t retry; /* Optional retry timeout if queue is blocked */
  83         } spec;
  84
  85         /* remaining fields should be opaque to users */
  86         STAILQ_HEAD(work_queue_items, work_queue_item)
  87         items;                /* queue item list */
  88         int item_count;       /* queued items */
  89         unsigned long runs;   /* runs count */
  90         unsigned long yields; /* yields count */
  91
  92         struct {
  93                 unsigned int best;
  94                 unsigned int granularity;
  95                 unsigned long total;
  96         } cycles; /* cycle counts */
  97
  98         /* private state */
  99         uint16_t flags; /* user set flag */
 100 };
 101
 102 /* User API */
 103
 104 static inline int work_queue_item_count(struct work_queue *wq)
 105 {
 106         return wq->item_count;
 107 }
 108
 109 static inline bool work_queue_empty(struct work_queue *wq)
 110 {
 111         return (wq->item_count == 0) ? true : false;
 112 }
 113
 114 static inline struct work_queue_item *
 115 work_queue_last_item(struct work_queue *wq)
 116 {
 117         return STAILQ_LAST(&wq->items, work_queue_item, wq);
 118 }
 119
 120 static inline void work_queue_item_enqueue(struct work_queue *wq,
 121                                            struct work_queue_item *item)
 122 {
 123         STAILQ_INSERT_TAIL(&wq->items, item, wq);
 124         wq->item_count++;
 125 }
 126
 127 static inline void work_queue_item_dequeue(struct work_queue *wq,
 128                                            struct work_queue_item *item)
 129 {
 130         assert(wq->item_count > 0);
 131
 132         wq->item_count--;
 133         STAILQ_REMOVE(&wq->items, item, work_queue_item, wq);
 134 }
 135
 136 /* create a new work queue, of given name.
 137  * user must fill in the spec of the returned work queue before adding
 138  * anything to it
 139  */
 140 extern struct work_queue *work_queue_new(struct thread_master *m,
 141                                          const char *queue_name);
 142
 143 /* destroy work queue */
 144 /*
 145  * The usage of work_queue_free is being transitioned to pass
 146  * in the double pointer to remove use after free's.
 147  */
 148 extern void work_queue_free_and_null(struct work_queue **wqp);
 149
 150 /* Add the supplied data as an item onto the workqueue */
 151 extern void work_queue_add(struct work_queue *wq, void *item);
 152
 153 /* plug the queue, ie prevent it from being drained / processed */
 154 extern void work_queue_plug(struct work_queue *wq);
 155 /* unplug the queue, allow it to be drained again */
 156 extern void work_queue_unplug(struct work_queue *wq);
 157
 158 bool work_queue_is_scheduled(struct work_queue *wq);
 159
 160 /* Helpers, exported for thread.c and command.c */
 161 extern void work_queue_run(struct thread *thread);
 162
 163 extern void workqueue_cmd_init(void);
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif
 168
 169 #endif /* _QUAGGA_WORK_QUEUE_H */