diff options
Diffstat (limited to 'nest/locks.c')
| -rw-r--r-- | nest/locks.c | 47 |
1 files changed, 47 insertions, 0 deletions
diff --git a/nest/locks.c b/nest/locks.c index 19a5df04..c1f7331e 100644 --- a/nest/locks.c +++ b/nest/locks.c @@ -6,6 +6,28 @@ * Can be freely distributed and used under the terms of the GNU GPL. */ +/** + * DOC: Object locks + * + * The lock module provides a simple mechanism for avoiding conflicts between + * various protocols which would like to use a single physical resource (for + * example a network port). It would be easy to say that such collisions can + * occur only when the user specifies an invalid configuration and therefore + * he deserves to get what he has asked for, but unfortunately they can also + * arise legitimately when the daemon is reconfigured and there exists (although + * for a short time period only) an old protocol being shut down and a new one + * willing to start up on the same interface. + * + * The solution is very simple: when any protocol wishes to use a network port + * or some other non-shareable resource, it asks the core to lock it and doesn't + * use the resource until it's notified that it has acquired the lock. + * + * Object locks are represented by &object_lock which is in turn a kind of + * resource. Lockable resources are uniquely determined by resource type + * (%OBJLOCK_UDP for a UDP port etc.), IP address (usually a broadcast or + * multicast address the port is bound to), port number and interface. + */ + #undef LOCAL_DEBUG #include "nest/bird.h" @@ -78,6 +100,14 @@ static struct resclass olock_class = { olock_dump }; +/** + * olock_new - create an object lock + * @p: resource pool to create the lock in. + * + * The olock_new() function creates a new resource of type &object_lock + * and returns a pointer to it. After filling in the structure, the caller + * should call olock_acquire() to do the real locking. + */ struct object_lock * olock_new(pool *p) { @@ -88,6 +118,17 @@ olock_new(pool *p) return l; } +/** + * olock_acquire - acquire a lock + * @l: the lock to acquire + * + * This function attempts to acquire exclusive access to the non-shareable + * resource described by the lock @l. It returns immediately, but as soon + * as the resource becomes available, it calls the hook() function set up + * by the caller. + * + * When you want to release the resource, just rfree() the lock. + */ void olock_acquire(struct object_lock *l) { @@ -134,6 +175,12 @@ olock_run_event(void *unused) } } +/** + * olock_init - initialize the object lock mechanism + * + * This function is called during BIRD startup. It initializes + * all the internal data structures of the lock module. + */ void olock_init(void) { |