BadVPN – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /**
2 * @file BEventLock.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 * A FIFO lock for events using the job queue ({@link BPending}).
32 */
33  
34 #ifndef BADVPN_BEVENTLOCK_H
35 #define BADVPN_BEVENTLOCK_H
36  
37 #include <misc/debugcounter.h>
38 #include <structure/LinkedList1.h>
39 #include <base/DebugObject.h>
40 #include <base/BPending.h>
41  
42 /**
43 * Event context handler called when the lock job has acquired the lock
44 * after requesting the lock with {@link BEventLockJob_Wait}.
45 * The object was in waiting state.
46 * The object enters locked state before the handler is called.
47 *
48 * @param user as in {@link BEventLockJob_Init}
49 */
50 typedef void (*BEventLock_handler) (void *user);
51  
52 /**
53 * A FIFO lock for events using the job queue ({@link BPending}).
54 */
55 typedef struct {
56 LinkedList1 jobs;
57 BPending exec_job;
58 DebugObject d_obj;
59 DebugCounter pending_ctr;
60 } BEventLock;
61  
62 /**
63 * An object that can request a {@link BEventLock} lock.
64 */
65 typedef struct {
66 BEventLock *l;
67 BEventLock_handler handler;
68 void *user;
69 int pending;
70 LinkedList1Node pending_node;
71 DebugObject d_obj;
72 } BEventLockJob;
73  
74 /**
75 * Initializes the object.
76 *
77 * @param o the object
78 * @param pg pending group
79 */
80 void BEventLock_Init (BEventLock *o, BPendingGroup *pg);
81  
82 /**
83 * Frees the object.
84 * There must be no {@link BEventLockJob} objects using this lock
85 * (regardless of their state).
86 *
87 * @param o the object
88 */
89 void BEventLock_Free (BEventLock *o);
90  
91 /**
92 * Initializes the object.
93 * The object is initialized in idle state.
94 *
95 * @param o the object
96 * @param l the lock
97 * @param handler handler to call when the lock is aquired
98 * @param user value to pass to handler
99 */
100 void BEventLockJob_Init (BEventLockJob *o, BEventLock *l, BEventLock_handler handler, void *user);
101  
102 /**
103 * Frees the object.
104 *
105 * @param o the object
106 */
107 void BEventLockJob_Free (BEventLockJob *o);
108  
109 /**
110 * Requests the lock.
111 * The object must be in idle state.
112 * The object enters waiting state.
113 *
114 * @param o the object
115 */
116 void BEventLockJob_Wait (BEventLockJob *o);
117  
118 /**
119 * Aborts the lock request or releases the lock.
120 * The object must be in waiting or locked state.
121 * The object enters idle state.
122 *
123 * @param o the object
124 */
125 void BEventLockJob_Release (BEventLockJob *o);
126  
127 #endif