From: Nuno Antunes <nuno.antunes@gmail.com>
Date: Mon, 16 Jul 2012 13:11:04 +0000 (+0100)
Subject: kernel/lwkt_msgport: Improve comments a bit.
X-Git-Tag: v3.2.0~575
X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/commitdiff_plain/1a0fa461533f94f7ccb37739ea94e735ff83eecf

kernel/lwkt_msgport: Improve comments a bit.

Reviewed-by: Sacha Wildner <swildner@>
---

diff --git a/sys/kern/lwkt_msgport.c b/sys/kern/lwkt_msgport.c
index 933b07da42..73436ed05e 100644
--- a/sys/kern/lwkt_msgport.c
+++ b/sys/kern/lwkt_msgport.c
@@ -97,6 +97,10 @@ lwkt_sendmsg(lwkt_port_t port, lwkt_msg_t msg)
 	     (msg->ms_flags & (MSGF_DONE|MSGF_QUEUED)) == MSGF_DONE);
     msg->ms_flags &= ~(MSGF_REPLY | MSGF_SYNC | MSGF_DONE);
     if ((error = lwkt_beginmsg(port, msg)) != EASYNC) {
+	/*
+	 * Target port opted to execute the message synchronously so
+	 * queue the response.
+	 */
 	lwkt_replymsg(msg, error);
     }
 }
@@ -104,10 +108,11 @@ lwkt_sendmsg(lwkt_port_t port, lwkt_msg_t msg)
 /*
  * lwkt_domsg()
  *
- *	Request asynchronous completion and call lwkt_beginmsg().  The
+ *	Request synchronous completion and call lwkt_beginmsg().  The
  *	target port can opt to execute the message synchronously or
- *	asynchronously and this function will automatically queue the
- *	response if the target executes the message synchronously.
+ *	asynchronously and this function will automatically block and
+ *	wait for a response if the target executes the message
+ *	asynchronously.
  */
 int
 lwkt_domsg(lwkt_port_t port, lwkt_msg_t msg, int flags)
@@ -119,6 +124,10 @@ lwkt_domsg(lwkt_port_t port, lwkt_msg_t msg, int flags)
     msg->ms_flags &= ~(MSGF_REPLY | MSGF_DONE);
     msg->ms_flags |= MSGF_SYNC;
     if ((error = lwkt_beginmsg(port, msg)) == EASYNC) {
+	/*
+	 * Target port opted to execute the message asynchronously so
+	 * block and wait for a reply.
+	 */
 	error = lwkt_waitmsg(msg, flags);
     } else {
 	msg->ms_flags |= MSGF_DONE | MSGF_REPLY;
@@ -706,6 +715,12 @@ lwkt_thread_waitmsg(lwkt_msg_t msg, int flags)
     return(msg->ms_error);
 }
 
+/*
+ * lwkt_thread_waitport()
+ *
+ *	Wait for a new message to be available on the port.  We must be the
+ *	the only thread waiting on the port.  The port must be owned by caller.
+ */
 static
 void *
 lwkt_thread_waitport(lwkt_port_t port, int flags)
diff --git a/sys/sys/msgport.h b/sys/sys/msgport.h
index e6bcdc4596..afbac3ec89 100644
--- a/sys/sys/msgport.h
+++ b/sys/sys/msgport.h
@@ -136,8 +136,8 @@ MALLOC_DECLARE(M_LWKTMSG);
  *	- reply a message (executed on the originating port to return a
  *	  message to it).  This can be rather involved if abort is to be
  *	  supported, see lwkt_default_replyport().  Generally speaking
- *	  one sets MSGF_DONE.  If MSGF_SYNC is set the message is not
- *	  queued to the port and the reply code wakes up the waiter
+ *	  one sets MSGF_DONE and MSGF_REPLY.  If MSGF_SYNC is set the message
+ *	  is not queued to the port and the reply code wakes up the waiter
  *	  directly.
  *
  * The use of mp_u.td and mp_u.spin is specific to the port callback function
@@ -173,10 +173,17 @@ typedef struct lwkt_port {
 
 #endif
 
+/*
+ * Port state flags.
+ *
+ * WAITING      The owner of the port is descheduled waiting for a message
+ *              to be replied.  In case this a spin port there can actually
+ *              be more than one thread waiting on the port.
+ */
 #define MSGPORTF_WAITING	0x0001
 
 /*
- * These functions are good for userland as well as the kernel.  The 
+ * These functions are good for userland as well as the kernel.  The
  * messaging function support for userland is provided by the kernel's
  * kern/lwkt_msgport.c.  The port functions are provided by userland.
  */