kernel/lwkt_msgport: Improve comments a bit.
authorNuno Antunes <nuno.antunes@gmail.com>
Mon, 16 Jul 2012 13:11:04 +0000 (14:11 +0100)
committerNuno Antunes <nuno.antunes@gmail.com>
Wed, 18 Jul 2012 11:34:30 +0000 (12:34 +0100)
Reviewed-by: Sacha Wildner <swildner@>
sys/kern/lwkt_msgport.c
sys/sys/msgport.h

index 933b07d..73436ed 100644 (file)
@@ -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)
index e6bcdc4..afbac3e 100644 (file)
@@ -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.
  */