From d3efda7e842a62943f4292760fe48d424a5b1c53 Mon Sep 17 00:00:00 2001 From: jcorgan Date: Sat, 16 Feb 2008 18:10:29 +0000 Subject: Improve hierarchical block documentation. git-svn-id: http://gnuradio.org/svn/gnuradio/trunk@7718 221aa14e-8319-0410-a670-987f0aec2ac5 --- gnuradio-core/src/lib/runtime/gr_hier_block2.h | 55 ++++++++++++++++++++++ gnuradio-core/src/lib/runtime/gr_top_block.h | 2 +- .../src/python/gnuradio/gr/hier_block2.py | 36 ++++++++++++-- 3 files changed, 87 insertions(+), 6 deletions(-) (limited to 'gnuradio-core/src') diff --git a/gnuradio-core/src/lib/runtime/gr_hier_block2.h b/gnuradio-core/src/lib/runtime/gr_hier_block2.h index d04acb970..5e67a9010 100644 --- a/gnuradio-core/src/lib/runtime/gr_hier_block2.h +++ b/gnuradio-core/src/lib/runtime/gr_hier_block2.h @@ -60,20 +60,75 @@ protected: public: virtual ~gr_hier_block2(); + /*! + * \brief Add a stand-alone (possibly hierarchical) block to internal graph + * + * This adds a gr-block or hierarchical block to the internal graph + * without wiring it to anything else. + */ void connect(gr_basic_block_sptr block); + /*! + * \brief Add gr-blocks or hierarchical blocks to internal graph and wire together + * + * This adds (if not done earlier by another connect) a pair of gr-blocks or + * hierarchical blocks to the internal flowgraph, and wires the specified output + * port to the specified input port. + */ void connect(gr_basic_block_sptr src, int src_port, gr_basic_block_sptr dst, int dst_port); + /*! + * \brief Remove a gr-block or hierarchical block from the internal flowgraph. + * + * This removes a gr-block or hierarchical block from the internal flowgraph, + * disconnecting it from other blocks as needed. + * + */ void disconnect(gr_basic_block_sptr block); + /*! + * \brief Disconnect a pair of gr-blocks or hierarchical blocks in internal + * flowgraph. + * + * This disconnects the specified input port from the specified output port + * of a pair of gr-blocks or hierarchical blocks. + */ void disconnect(gr_basic_block_sptr src, int src_port, gr_basic_block_sptr dst, int dst_port); + /*! + * \brief Disconnect all connections in the internal flowgraph. + * + * This call removes all output port to input port connections in the internal + * flowgraph. + */ void disconnect_all(); + + /*! + * Lock a flowgraph in preparation for reconfiguration. When an equal + * number of calls to lock() and unlock() have occurred, the flowgraph + * will be restarted automatically. + * + * N.B. lock() and unlock() cannot be called from a flowgraph thread + * (E.g., gr_block::work method) or deadlock will occur when + * reconfiguration happens. + */ virtual void lock(); + + /*! + * Unlock a flowgraph in preparation for reconfiguration. When an equal + * number of calls to lock() and unlock() have occurred, the flowgraph + * will be restarted automatically. + * + * N.B. lock() and unlock() cannot be called from a flowgraph thread + * (E.g., gr_block::work method) or deadlock will occur when + * reconfiguration happens. + */ virtual void unlock(); + // This is a public method for ease of code organization, but should be + // ignored by the user. gr_flat_flowgraph_sptr flatten() const; }; diff --git a/gnuradio-core/src/lib/runtime/gr_top_block.h b/gnuradio-core/src/lib/runtime/gr_top_block.h index 28814a9a0..0209546fe 100644 --- a/gnuradio-core/src/lib/runtime/gr_top_block.h +++ b/gnuradio-core/src/lib/runtime/gr_top_block.h @@ -89,7 +89,7 @@ public: virtual void lock(); /*! - * Lock a flowgraph in preparation for reconfiguration. When an equal + * Unlock a flowgraph in preparation for reconfiguration. When an equal * number of calls to lock() and unlock() have occurred, the flowgraph * will be restarted automatically. * diff --git a/gnuradio-core/src/python/gnuradio/gr/hier_block2.py b/gnuradio-core/src/python/gnuradio/gr/hier_block2.py index 1c096b709..b6dd40cd5 100644 --- a/gnuradio-core/src/python/gnuradio/gr/hier_block2.py +++ b/gnuradio-core/src/python/gnuradio/gr/hier_block2.py @@ -30,16 +30,36 @@ from gnuradio_swig_python import hier_block2_swig # It also allows us to intercept method calls if needed # class hier_block2(object): + """ + Python wrapper around the C++ hierarchical block implementation. + Provides convenience functions and allows proper Python subclassing. + """ + def __init__(self, name, input_signature, output_signature): + """ + Create a hierarchical block with a given name and I/O signatures. + """ self._hb = hier_block2_swig(name, input_signature, output_signature) def __getattr__(self, name): + """ + Pass-through member requests to the C++ object. + """ return getattr(self._hb, name) def connect(self, *points): - '''connect requires one or more arguments that can be coerced to endpoints. - If more than two arguments are provided, they are connected together successively. - ''' + """ + Connect two or more block endpoints. An endpoint is either a (block, port) + tuple, or just a block type. In the latter case, the port number is assumed + to be zero. + + To connect the hierarchical block external inputs or outputs to internal block + inputs or outputs, use 'self' in the connect call. + + If multiple arguments are provided, connect will attempt to wire them in series, + interpreting the endpoints as inputs or outputs as appropriate. + """ + if len (points) < 1: raise ValueError, ("connect requires at least one endpoint; %d provided." % (len (points),)) else: @@ -65,9 +85,15 @@ class hier_block2(object): raise ValueError("unable to coerce endpoint") def disconnect(self, *points): - '''connect requires one or more arguments that can be coerced to endpoints. + """ + Disconnect two endpoints in the flowgraph. + + To disconnect the hierarchical block external inputs or outputs to internal block + inputs or outputs, use 'self' in the connect call. + If more than two arguments are provided, they are disconnected successively. - ''' + """ + if len (points) < 1: raise ValueError, ("disconnect requires at least two endpoints; %d provided." % (len (points),)) else: -- cgit