From 8a5db53c3c3e41aa35fbd45aa7db23157619a4a7 Mon Sep 17 00:00:00 2001
From: Josh Blum
Date: Mon, 27 May 2013 22:09:16 -0700
Subject: gras: update the pop_input_msg documentation

---
 include/gras/block.hpp | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

(limited to 'include')

diff --git a/include/gras/block.hpp b/include/gras/block.hpp
index aab0a81..59c30c0 100644
--- a/include/gras/block.hpp
+++ b/include/gras/block.hpp
@@ -225,15 +225,19 @@ struct GRAS_API Block : Element
     void post_output_msg(const size_t which_output, const PMCC &msg);
 
     /*!
-     * Pop input message convenience routine.
-     * This routine reads the first input message,
-     * and erases this message from the given port.
-     * The intention is to simplify the use case
-     * for using this for port messages only.
-     * If no message, the return value is null.
+     * Pop a message from the specified port.
+     * This is a non-blocking call, and will return
+     * a null PMC when no message is available.
+     * Suppose PMCC msg = this->pop_input_msg(0);
+     * Use if(msg) to detect if the PMC is valid.
+     *
+     * There is no API to discover the queue depth.
+     * Therefore, users can either pop the queue exhaustively
+     * or call pop once and wait for work to be called again.
+     * If there are more messages, work is called again ASAP.
      *
      * \param which_input the index of the input port
-     * \return the message on the front of the queue
+     * \return the message on the port or null PMC
      */
     PMCC pop_input_msg(const size_t which_input);
 
-- 
cgit