From 2ffe34d6d245dea4284b6fc1a4fd8ec3ee4fd5e8 Mon Sep 17 00:00:00 2001
From: Mark Riddoch <mriddoch@ks211278.kimsufi.com>
Date: Thu, 27 Jun 2013 13:09:21 +0200
Subject: [PATCH] Updates to documentation

Switch polling mechanism back to the non-debug version
---
 core/poll.c                     | 18 ++++++++++++++++--
 modules/routing/debugcli.c      |  1 +
 modules/routing/debugcmd.c      |  3 ++-
 modules/routing/readconnroute.c |  1 +
 modules/routing/testroute.c     |  1 +
 5 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/core/poll.c b/core/poll.c
index 6bc93fcbf..267f36185 100644
--- a/core/poll.c
+++ b/core/poll.c
@@ -25,7 +25,7 @@
 #include <atomic.h>
 
 /**
- * @file poll.c  - Abraction of the epoll functionality
+ * @file poll.c  - Abstraction of the epoll functionality
  *
  * @verbatim
  * Revision History
@@ -104,7 +104,7 @@ struct	epoll_event	ev;
 	return epoll_ctl(epoll_fd, EPOLL_CTL_DEL, dcb->fd, &ev);
 }
 
-#define	BLOCKINGPOLL	1	/* Set BLOCKING POLL to 1 if using a single thread and to make
+#define	BLOCKINGPOLL	0	/* Set BLOCKING POLL to 1 if using a single thread and to make
 				 * debugging easier.
 				 */
 /**
@@ -112,6 +112,20 @@ struct	epoll_event	ev;
  *
  * This routine does the polling and despatches of IO events
  * to the DCB's
+ *
+ * The routine will loop as long as the variable "shutdown" is set to zero,
+ * setting this to a non-zero value will cause the polling loop to return.
+ *
+ * There are two options for the polling, a debug option that is only useful if
+ * you have a single thread. This blocks in epoll_wait until an event occurs.
+ *
+ * The non-debug option does an epoll with a time out. This allows the checking of
+ * shutdown value to be checked in all threads. The algorithm for polling in this
+ * mode is to do a poll with no-wait, if no events are detected then the poll is
+ * repeated with a time out. This allows for a quick check before making the call 
+ * with timeout. The call with the timeout differs in that the Linux scheduler may
+ * deschedule a process if a timeout is included, but will not do this if a 0 timeout
+ * value is given. this improves performance when the gateway is under heavy load.
  */
 void
 poll_waitevents()
diff --git a/modules/routing/debugcli.c b/modules/routing/debugcli.c
index b56881a41..da6676b5d 100644
--- a/modules/routing/debugcli.c
+++ b/modules/routing/debugcli.c
@@ -101,6 +101,7 @@ GetModuleObject()
  * within the gateway.
  * 
  * @param service	The service this router is being create for
+ * @param options	Any array of options for the query router
  *
  * @return The instance data for this new instance
  */
diff --git a/modules/routing/debugcmd.c b/modules/routing/debugcmd.c
index b2acf7b2c..5ed86ce42 100644
--- a/modules/routing/debugcmd.c
+++ b/modules/routing/debugcmd.c
@@ -166,7 +166,8 @@ static struct {
  * Convert a string argument to a numeric, observing prefixes
  * for number bases, e.g. 0x for hex, 0 for octal
  *
- * @param arg	The string representation of the argument
+ * @param arg		The string representation of the argument
+ * @param arg_type	The target type for the argument
  * @return The argument as a long integer
  */
 static unsigned long
diff --git a/modules/routing/readconnroute.c b/modules/routing/readconnroute.c
index 86f35ef76..cde9f6afa 100644
--- a/modules/routing/readconnroute.c
+++ b/modules/routing/readconnroute.c
@@ -121,6 +121,7 @@ GetModuleObject()
  * within the gateway.
  * 
  * @param service	The service this router is being create for
+ * @param options	An array of options for this query router
  *
  * @return The instance data for this new instance
  */
diff --git a/modules/routing/testroute.c b/modules/routing/testroute.c
index 80cd92178..8506ca136 100644
--- a/modules/routing/testroute.c
+++ b/modules/routing/testroute.c
@@ -69,6 +69,7 @@ GetModuleObject()
  * within the gateway.
  * 
  * @param service	The service this router is being create for
+ * @param options	The options for this query router
  *
  * @return The instance data for this new instance
  */