From: Hallvard Furuseth <hallvard@openldap.org>
Date: Mon, 23 Jan 2012 23:47:48 +0000 (+0100)
Subject: ITS#7125 Document connection loop API.
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=2b538761e998f71b8d4daf8e9c82d02912dc92da;p=openldap

ITS#7125 Document connection loop API.

Code comments belong in the code, not in commit messages.
---

diff --git a/servers/slapd/connection.c b/servers/slapd/connection.c
index b29e2f22f0..eb94af855f 100644
--- a/servers/slapd/connection.c
+++ b/servers/slapd/connection.c
@@ -864,6 +864,17 @@ unsigned long connections_nextid(void)
 	return id;
 }
 
+/*
+ * Loop through the connections:
+ *
+ *	for (c = connection_first(&i); c; c = connection_next(c, &i)) ...;
+ *	connection_done(c);
+ *
+ * 'i' is the cursor, initialized by connection_first().
+ * 'c_mutex' is locked in the returned connection.  The functions must
+ * be passed the previous return value so they can unlock it again.
+ */
+
 Connection* connection_first( ber_socket_t *index )
 {
 	assert( connections != NULL );
@@ -880,6 +891,7 @@ Connection* connection_first( ber_socket_t *index )
 	return connection_next(NULL, index);
 }
 
+/* Next connection in loop, see connection_first() */
 Connection* connection_next( Connection *c, ber_socket_t *index )
 {
 	assert( connections != NULL );
@@ -928,6 +940,7 @@ Connection* connection_next( Connection *c, ber_socket_t *index )
 	return c;
 }
 
+/* End connection loop, see connection_first() */
 void connection_done( Connection *c )
 {
 	assert( connections != NULL );