summaryrefslogtreecommitdiffstats
path: root/nest/locks.c
diff options
context:
space:
mode:
Diffstat (limited to 'nest/locks.c')
-rw-r--r--nest/locks.c47
1 files changed, 47 insertions, 0 deletions
diff --git a/nest/locks.c b/nest/locks.c
index 19a5df0..c1f7331 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)
{