[Commit-gnuradio] [gnuradio] 01/03: runtime: better documentation for the set min/max output buffer functions.

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch master
in repository gnuradio.

commit 429c6f9639bcd1ababe1090a9154be3402c270a8
Author: Tom Rondeau <address@hidden>
Date:   Thu Apr 9 10:58:07 2015 -0400

    runtime: better documentation for the set min/max output buffer functions.
---
 gnuradio-runtime/include/gnuradio/block.h | 63 +++++++++++++++++++++++++++++--
 gnuradio-runtime/lib/flat_flowgraph.cc    |  9 ++---
 2 files changed, 62 insertions(+), 10 deletions(-)

diff --git a/gnuradio-runtime/include/gnuradio/block.h 
b/gnuradio-runtime/include/gnuradio/block.h
index 264ef9b..85bcd29 100644
--- a/gnuradio-runtime/include/gnuradio/block.h
+++ b/gnuradio-runtime/include/gnuradio/block.h
@@ -367,12 +367,39 @@ namespace gr {
     long max_output_buffer(size_t i);
 
     /*!
-     * \brief Sets max buffer size on all output ports.
+     * \brief Request limit on max buffer size on all output ports.
+     *
+     * \details
+     * This is an advanced feature. Calling this can affect some
+     * fundamental assumptions about the system behavior and
+     * performance.
+     *
+     * The actual buffer size is determined by a number of other
+     * factors from the block and system. This function only provides
+     * a requested maximum. The buffers will always be a multiple of
+     * the system page size, which may be larger than the value asked
+     * for here.
+     *
+     * \param max_output_buffer the requested maximum output size in items.
      */
     void set_max_output_buffer(long max_output_buffer);
 
     /*!
-     * \brief Sets max buffer size on output port \p port.
+     * \brief Request limit on max buffer size on output port \p port.
+     *
+     * \details
+     * This is an advanced feature. Calling this can affect some
+     * fundamental assumptions about the system behavior and
+     * performance.
+     *
+     * The actual buffer size is determined by a number of other
+     * factors from the block and system. This function only provides
+     * a requested maximum. The buffers will always be a multiple of
+     * the system page size, which may be larger than the value asked
+     * for here.
+     *
+     * \parem port the output port the request applies to.
+     * \param max_output_buffer the requested maximum output size in items.
      */
     void set_max_output_buffer(int port, long max_output_buffer);
 
@@ -382,12 +409,40 @@ namespace gr {
     long min_output_buffer(size_t i);
 
     /*!
-     * \brief Sets min buffer size on all output ports.
+     * \brief Request limit on the mininum buffer size on all output
+     * ports.
+     *
+     * \details
+     * This is an advanced feature. Calling this can affect some
+     * fundamental assumptions about the system behavior and
+     * performance.
+     *
+     * The actual buffer size is determined by a number of other
+     * factors from the block and system. This function only provides
+     * a requested minimum. The buffers will always be a multiple of
+     * the system page size, which may be larger than the value asked
+     * for here.
+     *
+     * \param min_output_buffer the requested minimum output size in items.
      */
     void set_min_output_buffer(long min_output_buffer);
 
     /*!
-     * \brief Sets min buffer size on output port \p port.
+     * \brief Request limit on min buffer size on output port \p port.
+     *
+     * \details
+     * This is an advanced feature. Calling this can affect some
+     * fundamental assumptions about the system behavior and
+     * performance.
+     *
+     * The actual buffer size is determined by a number of other
+     * factors from the block and system. This function only provides
+     * a requested minimum. The buffers will always be a multiple of
+     * the system page size, which may be larger than the value asked
+     * for here.
+     *
+     * \parem port the output port the request applies to.
+     * \param min_output_buffer the requested minimum output size in items.
      */
     void set_min_output_buffer(int port, long min_output_buffer);
 
diff --git a/gnuradio-runtime/lib/flat_flowgraph.cc 
b/gnuradio-runtime/lib/flat_flowgraph.cc
index b580238..56123fc 100644
--- a/gnuradio-runtime/lib/flat_flowgraph.cc
+++ b/gnuradio-runtime/lib/flat_flowgraph.cc
@@ -109,12 +109,9 @@ namespace gr {
 
       // Update the block's max_output_buffer based on what was actually 
allocated.
       if((grblock->max_output_buffer(i) != buffer->bufsize()) && 
(grblock->max_output_buffer(i) != -1))
-        GR_LOG_WARN(d_logger, boost::format("Block (%1%) max output buffer set 
to %2% instead of requested %3%") \
-                      % grblock->alias() % buffer->bufsize() % 
grblock->max_output_buffer(i));
-        //std::cout << ">>> Warning: Block (" << grblock->alias()
-        //          << ") max output buffer set to " << buffer->bufsize()
-        //          << " instead of requested " << 
grblock->max_output_buffer(i)
-        //          << std::endl;
+        GR_LOG_WARN(d_logger, boost::format("Block (%1%) max output buffer set 
to %2%"
+                                            " instead of requested %3%") \
+                    % grblock->alias() % buffer->bufsize() % 
grblock->max_output_buffer(i));
       grblock->set_max_output_buffer(i, buffer->bufsize());
     }