GNU Radio 3.4.0 C++ API
gr_hier_block2.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2006,2007,2008,2009 Free Software Foundation, Inc.
00004  * 
00005  * This file is part of GNU Radio
00006  * 
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  * 
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  * 
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 #ifndef INCLUDED_GR_HIER_BLOCK2_H
00023 #define INCLUDED_GR_HIER_BLOCK2_H
00024 
00025 #include <gr_basic_block.h>
00026 
00027 /*!
00028  * \brief public constructor for gr_hier_block2
00029 
00030  */
00031 gr_hier_block2_sptr gr_make_hier_block2(const std::string &name,
00032                                         gr_io_signature_sptr input_signature,
00033                                         gr_io_signature_sptr output_signature);
00034 
00035 class gr_hier_block2_detail;
00036 
00037 /*!
00038  * \brief Hierarchical container class for gr_block's and gr_hier_block2's
00039  * \ingroup container_blk
00040  * \ingroup base_blk
00041  *
00042  */
00043 class gr_hier_block2 : public gr_basic_block
00044 {
00045 private:
00046   friend class gr_hier_block2_detail;
00047   friend gr_hier_block2_sptr gr_make_hier_block2(const std::string &name,
00048                                                  gr_io_signature_sptr input_signature,
00049                                                  gr_io_signature_sptr output_signature);
00050   
00051   /*!
00052    * \brief Private implementation details of gr_hier_block2
00053    */
00054   gr_hier_block2_detail *d_detail;
00055     
00056 protected: 
00057   gr_hier_block2(const std::string &name,
00058                  gr_io_signature_sptr input_signature,
00059                  gr_io_signature_sptr output_signature);
00060   
00061 public:
00062   virtual ~gr_hier_block2();
00063   
00064   /*!
00065    * \brief typedef for object returned from self().
00066    *
00067    * This type is only guaranteed to be passable to connect and disconnect.
00068    * No other assumptions should be made about it.
00069    */
00070   typedef gr_basic_block_sptr   opaque_self;
00071 
00072   /*!
00073    * \brief Return an object, representing the current block, which can be passed to connect.
00074    *
00075    * The returned object may only be used as an argument to connect or disconnect.
00076    * Any other use of self() results in unspecified (erroneous) behavior.
00077    */
00078   opaque_self self();
00079 
00080   /*!
00081    * \brief Add a stand-alone (possibly hierarchical) block to internal graph
00082    *
00083    * This adds a gr-block or hierarchical block to the internal graph
00084    * without wiring it to anything else.
00085    */
00086   void connect(gr_basic_block_sptr block);
00087 
00088   /*!
00089    * \brief Add gr-blocks or hierarchical blocks to internal graph and wire together
00090    *
00091    * This adds (if not done earlier by another connect) a pair of gr-blocks or 
00092    * hierarchical blocks to the internal flowgraph, and wires the specified output 
00093    * port to the specified input port.
00094    */
00095   void connect(gr_basic_block_sptr src, int src_port, 
00096                gr_basic_block_sptr dst, int dst_port);
00097 
00098   /*!
00099    * \brief Remove a gr-block or hierarchical block from the internal flowgraph.
00100    *
00101    * This removes a gr-block or hierarchical block from the internal flowgraph,
00102    * disconnecting it from other blocks as needed.
00103    *
00104    */
00105   void disconnect(gr_basic_block_sptr block);
00106 
00107   /*!
00108    * \brief Disconnect a pair of gr-blocks or hierarchical blocks in internal
00109    *        flowgraph.
00110    *
00111    * This disconnects the specified input port from the specified output port
00112    * of a pair of gr-blocks or hierarchical blocks.
00113    */
00114   void disconnect(gr_basic_block_sptr src, int src_port,
00115                   gr_basic_block_sptr dst, int dst_port);
00116 
00117   /*!
00118    * \brief Disconnect all connections in the internal flowgraph.
00119    *
00120    * This call removes all output port to input port connections in the internal
00121    * flowgraph.
00122    */
00123   void disconnect_all();
00124 
00125   /*!
00126    * Lock a flowgraph in preparation for reconfiguration.  When an equal
00127    * number of calls to lock() and unlock() have occurred, the flowgraph
00128    * will be reconfigured.
00129    *
00130    * N.B. lock() and unlock() may not be called from a flowgraph thread
00131    * (E.g., gr_block::work method) or deadlock will occur when
00132    * reconfiguration happens.
00133    */
00134   virtual void lock();
00135 
00136   /*!
00137    * Unlock a flowgraph in preparation for reconfiguration.  When an equal
00138    * number of calls to lock() and unlock() have occurred, the flowgraph
00139    * will be reconfigured.
00140    *
00141    * N.B. lock() and unlock() may not be called from a flowgraph thread
00142    * (E.g., gr_block::work method) or deadlock will occur when
00143    * reconfiguration happens.
00144    */
00145   virtual void unlock();
00146 
00147   // This is a public method for ease of code organization, but should be
00148   // ignored by the user.
00149   gr_flat_flowgraph_sptr flatten() const;
00150 
00151   gr_hier_block2_sptr to_hier_block2(); // Needed for Python/Guile type coercion
00152 };
00153 
00154 inline gr_hier_block2_sptr cast_to_hier_block2_sptr(gr_basic_block_sptr block) {
00155   return boost::dynamic_pointer_cast<gr_hier_block2, gr_basic_block>(block);
00156 }
00157 
00158 #endif /* INCLUDED_GR_HIER_BLOCK2_H */