blob: 15c72f62f325abd4d4e1108f9ba209c82bcdbfc9 [file] [log] [blame]
paul354d1192005-04-25 16:26:42 +00001/*
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/* Work queue default hold and cycle times - millisec */
paul190880d2005-11-14 12:07:47 +000028#define WORK_QUEUE_DEFAULT_HOLD 50 /* hold-time between runs of a queue */
29#define WORK_QUEUE_DEFAULT_DELAY 10 /* minimum delay for queue runs */
30#define WORK_QUEUE_DEFAULT_FLOOD 40 /* flood factor, ~2s with prev values */
paul354d1192005-04-25 16:26:42 +000031
32/* action value, for use by item processor and item error handlers */
33typedef enum
34{
35 WQ_SUCCESS = 0,
36 WQ_ERROR, /* Error, run error handler if provided */
37 WQ_RETRY_NOW, /* retry immediately */
38 WQ_RETRY_LATER, /* retry later, cease processing work queue */
paul269d74f2005-05-23 13:42:46 +000039 WQ_REQUEUE, /* requeue item, continue processing work queue */
40 WQ_QUEUE_BLOCKED, /* Queue cant be processed at this time.
41 * Similar to WQ_RETRY_LATER, but doesn't penalise
42 * the particular item.. */
paul354d1192005-04-25 16:26:42 +000043} wq_item_status;
44
45/* A single work queue item, unsurprisingly */
46struct work_queue_item
47{
48 void *data; /* opaque data */
paul84369682005-04-27 12:39:27 +000049 unsigned short ran; /* # of times item has been run */
paul354d1192005-04-25 16:26:42 +000050};
51
paul269d74f2005-05-23 13:42:46 +000052enum work_queue_flags
53{
54 WQ_UNPLUGGED = 0,
55 WQ_PLUGGED = 1,
56};
57
paul354d1192005-04-25 16:26:42 +000058struct work_queue
59{
paul190880d2005-11-14 12:07:47 +000060 /* Everything but the specification struct is private */
paul354d1192005-04-25 16:26:42 +000061 struct thread_master *master; /* thread master */
62 struct thread *thread; /* thread, if one is active */
63 char *name; /* work queue name */
paul190880d2005-11-14 12:07:47 +000064 char status; /* status */
65#define WQ_STATE_FLOODED (1 << 0)
paul269d74f2005-05-23 13:42:46 +000066 enum work_queue_flags flags; /* flags */
paul354d1192005-04-25 16:26:42 +000067
paul190880d2005-11-14 12:07:47 +000068 /* Specification for this work queue.
69 * Public, must be set before use by caller. May be modified at will.
70 */
paul354d1192005-04-25 16:26:42 +000071 struct {
72 /* work function to process items with */
paul8cc41982005-05-06 21:25:49 +000073 wq_item_status (*workfunc) (void *);
paul354d1192005-04-25 16:26:42 +000074
75 /* error handling function, optional */
76 void (*errorfunc) (struct work_queue *, struct work_queue_item *);
77
78 /* callback to delete user specific item data */
paul8cc41982005-05-06 21:25:49 +000079 void (*del_item_data) (void *);
paul354d1192005-04-25 16:26:42 +000080
paul269d74f2005-05-23 13:42:46 +000081 /* completion callback, called when queue is emptied, optional */
82 void (*completion_func) (struct work_queue *);
83
paul354d1192005-04-25 16:26:42 +000084 /* max number of retries to make for item that errors */
85 unsigned int max_retries;
86
87 unsigned int hold; /* hold time for first run, in ms */
88 unsigned int delay; /* min delay between queue runs, in ms */
paul190880d2005-11-14 12:07:47 +000089
90 unsigned int flood; /* number of queue runs after which we consider
91 * queue to be flooded, where the runs are
92 * consecutive and each has used its full slot,
93 * and the queue has still not been cleared. If
94 * the queue is flooded, then we try harder to
95 * clear it by ignoring the hold and delay
96 * times. No point sparing CPU resources just
97 * to use ever more memory resources.
98 */
paul354d1192005-04-25 16:26:42 +000099 } spec;
100
101 /* remaining fields should be opaque to users */
102 struct list *items; /* queue item list */
paul269d74f2005-05-23 13:42:46 +0000103 unsigned long runs; /* runs count */
paul190880d2005-11-14 12:07:47 +0000104 unsigned int runs_since_clear; /* number of runs since queue was
105 * last cleared
106 */
paul354d1192005-04-25 16:26:42 +0000107
108 struct {
109 unsigned int best;
110 unsigned int granularity;
111 unsigned long total;
112 } cycles; /* cycle counts */
113};
114
115/* User API */
paul269d74f2005-05-23 13:42:46 +0000116
117/* create a new work queue, of given name.
118 * user must fill in the spec of the returned work queue before adding
119 * anything to it
120 */
paul8cc41982005-05-06 21:25:49 +0000121extern struct work_queue *work_queue_new (struct thread_master *,
122 const char *);
paul269d74f2005-05-23 13:42:46 +0000123/* destroy work queue */
paul8cc41982005-05-06 21:25:49 +0000124extern void work_queue_free (struct work_queue *);
paul269d74f2005-05-23 13:42:46 +0000125
126/* Add the supplied data as an item onto the workqueue */
paul8cc41982005-05-06 21:25:49 +0000127extern void work_queue_add (struct work_queue *, void *);
paul354d1192005-04-25 16:26:42 +0000128
paul269d74f2005-05-23 13:42:46 +0000129/* plug the queue, ie prevent it from being drained / processed */
130extern void work_queue_plug (struct work_queue *wq);
131/* unplug the queue, allow it to be drained again */
132extern void work_queue_unplug (struct work_queue *wq);
133
paul354d1192005-04-25 16:26:42 +0000134/* Helpers, exported for thread.c and command.c */
paul8cc41982005-05-06 21:25:49 +0000135extern int work_queue_run (struct thread *);
paul354d1192005-04-25 16:26:42 +0000136extern struct cmd_element show_work_queues_cmd;
137#endif /* _QUAGGA_WORK_QUEUE_H */