BadVPN – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /**
2 * @file BPending.h
3 * @author Ambroz Bizjak <ambrop7@gmail.com>
4 *
5 * @section LICENSE
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * 3. Neither the name of the author nor the
15 * names of its contributors may be used to endorse or promote products
16 * derived from this software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
19 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
22 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
25 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 *
29 * @section DESCRIPTION
30 *
31 * Module for managing a queue of jobs pending execution.
32 */
33  
34 #ifndef BADVPN_BPENDING_H
35 #define BADVPN_BPENDING_H
36  
37 #include <stdint.h>
38  
39 #include <misc/debugcounter.h>
40 #include <structure/SLinkedList.h>
41 #include <base/DebugObject.h>
42  
43 struct BSmallPending_s;
44  
45 #include "BPending_list.h"
46 #include <structure/SLinkedList_decl.h>
47  
48 /**
49 * Job execution handler.
50 * It is guaranteed that the associated {@link BSmallPending} object was
51 * in set state.
52 * The {@link BSmallPending} object enters not set state before the handler
53 * is called.
54 *
55 * @param user as in {@link BSmallPending_Init}
56 */
57 typedef void (*BSmallPending_handler) (void *user);
58  
59 /**
60 * Job execution handler.
61 * It is guaranteed that the associated {@link BPending} object was
62 * in set state.
63 * The {@link BPending} object enters not set state before the handler
64 * is called.
65 *
66 * @param user as in {@link BPending_Init}
67 */
68 typedef void (*BPending_handler) (void *user);
69  
70 /**
71 * Object that contains a list of jobs pending execution.
72 */
73 typedef struct {
74 BPending__List jobs;
75 DebugCounter pending_ctr;
76 DebugObject d_obj;
77 } BPendingGroup;
78  
79 /**
80 * Object for queuing a job for execution.
81 */
82 typedef struct BSmallPending_s {
83 BPending_handler handler;
84 void *user;
85 BPending__ListNode pending_node; // optimization: if not pending, .next is this
86 #ifndef NDEBUG
87 uint8_t pending;
88 #endif
89 DebugObject d_obj;
90 } BSmallPending;
91  
92 /**
93 * Object for queuing a job for execution. This is a convenience wrapper
94 * around {@link BSmallPending} with an extra field to remember the
95 * {@link BPendingGroup} being used.
96 */
97 typedef struct {
98 BSmallPending base;
99 BPendingGroup *g;
100 } BPending;
101  
102 /**
103 * Initializes the object.
104 *
105 * @param g the object
106 */
107 void BPendingGroup_Init (BPendingGroup *g);
108  
109 /**
110 * Frees the object.
111 * There must be no {@link BPending} or {@link BSmallPending} objects using
112 * this group.
113 *
114 * @param g the object
115 */
116 void BPendingGroup_Free (BPendingGroup *g);
117  
118 /**
119 * Checks if there is at least one job in the queue.
120 *
121 * @param g the object
122 * @return 1 if there is at least one job, 0 if not
123 */
124 int BPendingGroup_HasJobs (BPendingGroup *g);
125  
126 /**
127 * Executes the top job on the job list.
128 * The job is removed from the list and enters
129 * not set state before being executed.
130 * There must be at least one job in job list.
131 *
132 * @param g the object
133 */
134 void BPendingGroup_ExecuteJob (BPendingGroup *g);
135  
136 /**
137 * Returns the top job on the job list, or NULL if there are none.
138 *
139 * @param g the object
140 * @return the top job if there is at least one job, NULL if not
141 */
142 BSmallPending * BPendingGroup_PeekJob (BPendingGroup *g);
143  
144 /**
145 * Initializes the object.
146 * The object is initialized in not set state.
147 *
148 * @param o the object
149 * @param g pending group to use
150 * @param handler job execution handler
151 * @param user value to pass to handler
152 */
153 void BSmallPending_Init (BSmallPending *o, BPendingGroup *g, BSmallPending_handler handler, void *user);
154  
155 /**
156 * Frees the object.
157 * The execution handler will not be called after the object
158 * is freed.
159 *
160 * @param o the object
161 * @param g pending group. Must be the same as was used in {@link BSmallPending_Init}.
162 */
163 void BSmallPending_Free (BSmallPending *o, BPendingGroup *g);
164  
165 /**
166 * Changes the job execution handler.
167 *
168 * @param o the object
169 * @param handler job execution handler
170 * @param user value to pass to handler
171 */
172 void BSmallPending_SetHandler (BSmallPending *o, BSmallPending_handler handler, void *user);
173  
174 /**
175 * Enables the job, pushing it to the top of the job list.
176 * If the object was already in set state, the job is removed from its
177 * current position in the list before being pushed.
178 * The object enters set state.
179 *
180 * @param o the object
181 * @param g pending group. Must be the same as was used in {@link BSmallPending_Init}.
182 */
183 void BSmallPending_Set (BSmallPending *o, BPendingGroup *g);
184  
185 /**
186 * Disables the job, removing it from the job list.
187 * If the object was not in set state, nothing is done.
188 * The object enters not set state.
189 *
190 * @param o the object
191 * @param g pending group. Must be the same as was used in {@link BSmallPending_Init}.
192 */
193 void BSmallPending_Unset (BSmallPending *o, BPendingGroup *g);
194  
195 /**
196 * Checks if the job is in set state.
197 *
198 * @param o the object
199 * @return 1 if in set state, 0 if not
200 */
201 int BSmallPending_IsSet (BSmallPending *o);
202  
203 /**
204 * Initializes the object.
205 * The object is initialized in not set state.
206 *
207 * @param o the object
208 * @param g pending group to use
209 * @param handler job execution handler
210 * @param user value to pass to handler
211 */
212 void BPending_Init (BPending *o, BPendingGroup *g, BPending_handler handler, void *user);
213  
214 /**
215 * Frees the object.
216 * The execution handler will not be called after the object
217 * is freed.
218 *
219 * @param o the object
220 */
221 void BPending_Free (BPending *o);
222  
223 /**
224 * Enables the job, pushing it to the top of the job list.
225 * If the object was already in set state, the job is removed from its
226 * current position in the list before being pushed.
227 * The object enters set state.
228 *
229 * @param o the object
230 */
231 void BPending_Set (BPending *o);
232  
233 /**
234 * Disables the job, removing it from the job list.
235 * If the object was not in set state, nothing is done.
236 * The object enters not set state.
237 *
238 * @param o the object
239 */
240 void BPending_Unset (BPending *o);
241  
242 /**
243 * Checks if the job is in set state.
244 *
245 * @param o the object
246 * @return 1 if in set state, 0 if not
247 */
248 int BPending_IsSet (BPending *o);
249  
250 #endif