Revision 1f495723 nest/locks.c

View differences:

nest/locks.c
6 6
 *	Can be freely distributed and used under the terms of the GNU GPL.
7 7
 */
8 8

  
9
/**
10
 * DOC: Object locks
11
 *
12
 * The lock module provides a simple mechanism for avoiding conflicts between
13
 * various protocols which would like to use a single physical resource (for
14
 * example a network port). It would be easy to say that such collisions can
15
 * occur only when the user specifies an invalid configuration and therefore
16
 * he deserves to get what he has asked for, but unfortunately they can also
17
 * arise legitimately when the daemon is reconfigured and there exists (although
18
 * for a short time period only) an old protocol being shut down and a new one
19
 * willing to start up on the same interface.
20
 *
21
 * The solution is very simple: when any protocol wishes to use a network port
22
 * or some other non-shareable resource, it asks the core to lock it and doesn't
23
 * use the resource until it's notified that it has acquired the lock.
24
 *
25
 * Object locks are represented by &object_lock which is in turn a kind of
26
 * resource. Lockable resources are uniquely determined by resource type
27
 * (%OBJLOCK_UDP for a UDP port etc.), IP address (usually a broadcast or
28
 * multicast address the port is bound to), port number and interface.
29
 */
30

  
9 31
#undef LOCAL_DEBUG
10 32

  
11 33
#include "nest/bird.h"
......
78 100
  olock_dump
79 101
};
80 102

  
103
/**
104
 * olock_new - create an object lock
105
 * @p: resource pool to create the lock in.
106
 *
107
 * The olock_new() function creates a new resource of type &object_lock
108
 * and returns a pointer to it. After filling in the structure, the caller
109
 * should call olock_acquire() to do the real locking.
110
 */
81 111
struct object_lock *
82 112
olock_new(pool *p)
83 113
{
......
88 118
  return l;
89 119
}
90 120

  
121
/**
122
 * olock_acquire - acquire a lock
123
 * @l: the lock to acquire
124
 *
125
 * This function attempts to acquire exclusive access to the non-shareable
126
 * resource described by the lock @l. It returns immediately, but as soon
127
 * as the resource becomes available, it calls the hook() function set up
128
 * by the caller.
129
 *
130
 * When you want to release the resource, just rfree() the lock.
131
 */
91 132
void
92 133
olock_acquire(struct object_lock *l)
93 134
{
......
134 175
    }
135 176
}
136 177

  
178
/**
179
 * olock_init - initialize the object lock mechanism
180
 *
181
 * This function is called during BIRD startup. It initializes
182
 * all the internal data structures of the lock module.
183
 */
137 184
void
138 185
olock_init(void)
139 186
{

Also available in: Unified diff