1/*
2 * Quagga Work Queues.
3 *
4 * Copyright (C) 2005 Sun Microsystems, Inc.
5 *
6 * This file is part of Quagga.
7 *
8 * Quagga is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU General Public License as published by the
10 * Free Software Foundation; either version 2, or (at your option) any
11 * later version.
12 *
13 * Quagga is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16 * General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with Quagga; see the file COPYING.  If not, write to the Free
20 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
21 * 02111-1307, USA.
22 */
23
24#ifndef _QUAGGA_WORK_QUEUE_H
25#define _QUAGGA_WORK_QUEUE_H
26
27/* Hold time for the initial schedule of a queue run, in  millisec */
28#define WORK_QUEUE_DEFAULT_HOLD  50
29
30/* action value, for use by item processor and item error handlers */
31typedef enum
32{
33  WQ_SUCCESS = 0,
34  WQ_ERROR,             /* Error, run error handler if provided */
35  WQ_RETRY_NOW,         /* retry immediately */
36  WQ_RETRY_LATER,       /* retry later, cease processing work queue */
37  WQ_REQUEUE,		/* requeue item, continue processing work queue */
38  WQ_QUEUE_BLOCKED,	/* Queue cant be processed at this time.
39                         * Similar to WQ_RETRY_LATER, but doesn't penalise
40                         * the particular item.. */
41} wq_item_status;
42
43/* A single work queue item, unsurprisingly */
44struct work_queue_item
45{
46  void *data;                           /* opaque data */
47  unsigned short ran;			/* # of times item has been run */
48};
49
50#define WQ_UNPLUGGED	(1 << 0) /* available for draining */
51
52struct work_queue
53{
54  /* Everything but the specification struct is private
55   * the following may be read
56   */
57  struct thread_master *master;       /* thread master */
58  struct thread *thread;              /* thread, if one is active */
59  char *name;                         /* work queue name */
60
61  /* Specification for this work queue.
62   * Public, must be set before use by caller. May be modified at will.
63   */
64  struct {
65    /* optional opaque user data, global to the queue. */
66    void *data;
67
68    /* work function to process items with:
69     * First argument is the workqueue queue.
70     * Second argument is the item data
71     */
72    wq_item_status (*workfunc) (struct work_queue *, void *);
73
74    /* error handling function, optional */
75    void (*errorfunc) (struct work_queue *, struct work_queue_item *);
76
77    /* callback to delete user specific item data */
78    void (*del_item_data) (struct work_queue *, void *);
79
80    /* completion callback, called when queue is emptied, optional */
81    void (*completion_func) (struct work_queue *);
82
83    /* max number of retries to make for item that errors */
84    unsigned int max_retries;
85
86    unsigned int hold;	/* hold time for first run, in ms */
87  } spec;
88
89  /* remaining fields should be opaque to users */
90  struct list *items;                 /* queue item list */
91  unsigned long runs;                 /* runs count */
92
93  struct {
94    unsigned int best;
95    unsigned int granularity;
96    unsigned long total;
97  } cycles;	/* cycle counts */
98
99  /* private state */
100  u_int16_t flags;		/* user set flag */
101};
102
103/* User API */
104
105/* create a new work queue, of given name.
106 * user must fill in the spec of the returned work queue before adding
107 * anything to it
108 */
109extern struct work_queue *work_queue_new (struct thread_master *,
110                                          const char *);
111/* destroy work queue */
112extern void work_queue_free (struct work_queue *);
113
114/* Add the supplied data as an item onto the workqueue */
115extern void work_queue_add (struct work_queue *, void *);
116
117/* plug the queue, ie prevent it from being drained / processed */
118extern void work_queue_plug (struct work_queue *wq);
119/* unplug the queue, allow it to be drained again */
120extern void work_queue_unplug (struct work_queue *wq);
121
122/* Helpers, exported for thread.c and command.c */
123extern int work_queue_run (struct thread *);
124extern struct cmd_element show_work_queues_cmd;
125#endif /* _QUAGGA_WORK_QUEUE_H */
126