git.gag.com Git - debian/gnuradio/blob - gnuradio-core/src/lib/runtime/gr_hier_block2.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2006,2007,2008,2009 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   7  * GNU Radio is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 3, or (at your option)
  10  * any later version.
  11  *
  12  * GNU Radio is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with GNU Radio; see the file COPYING.  If not, write to
  19  * the Free Software Foundation, Inc., 51 Franklin Street,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22 #ifndef INCLUDED_GR_HIER_BLOCK2_H
  23 #define INCLUDED_GR_HIER_BLOCK2_H
  24
  25 #include <gr_basic_block.h>
  26
  27 /*!
  28  * \brief public constructor for gr_hier_block2
  29
  30  */
  31 gr_hier_block2_sptr gr_make_hier_block2(const std::string &name,
  32                                         gr_io_signature_sptr input_signature,
  33                                         gr_io_signature_sptr output_signature);
  34
  35 class gr_hier_block2_detail;
  36
  37 /*!
  38  * \brief Hierarchical container class for gr_block's and gr_hier_block2's
  39  * \ingroup container_blk
  40  * \ingroup base_blk
  41  *
  42  */
  43 class gr_hier_block2 : public gr_basic_block
  44 {
  45 private:
  46   friend class gr_hier_block2_detail;
  47   friend gr_hier_block2_sptr gr_make_hier_block2(const std::string &name,
  48                                                  gr_io_signature_sptr input_signature,
  49                                                  gr_io_signature_sptr output_signature);
  50
  51   /*!
  52    * \brief Private implementation details of gr_hier_block2
  53    */
  54   gr_hier_block2_detail *d_detail;
  55
  56 protected:
  57   gr_hier_block2(const std::string &name,
  58                  gr_io_signature_sptr input_signature,
  59                  gr_io_signature_sptr output_signature);
  60
  61 public:
  62   virtual ~gr_hier_block2();
  63
  64   /*!
  65    * \brief typedef for object returned from self().
  66    *
  67    * This type is only guaranteed to be passable to connect and disconnect.
  68    * No other assumptions should be made about it.
  69    */
  70   typedef gr_basic_block_sptr   opaque_self;
  71
  72   /*!
  73    * \brief Return an object, representing the current block, which can be passed to connect.
  74    *
  75    * The returned object may only be used as an argument to connect or disconnect.
  76    * Any other use of self() results in unspecified (erroneous) behavior.
  77    */
  78   opaque_self self();
  79
  80   /*!
  81    * \brief Add a stand-alone (possibly hierarchical) block to internal graph
  82    *
  83    * This adds a gr-block or hierarchical block to the internal graph
  84    * without wiring it to anything else.
  85    */
  86   void connect(gr_basic_block_sptr block);
  87
  88   /*!
  89    * \brief Add gr-blocks or hierarchical blocks to internal graph and wire together
  90    *
  91    * This adds (if not done earlier by another connect) a pair of gr-blocks or
  92    * hierarchical blocks to the internal flowgraph, and wires the specified output
  93    * port to the specified input port.
  94    */
  95   void connect(gr_basic_block_sptr src, int src_port,
  96                gr_basic_block_sptr dst, int dst_port);
  97
  98   /*!
  99    * \brief Remove a gr-block or hierarchical block from the internal flowgraph.
 100    *
 101    * This removes a gr-block or hierarchical block from the internal flowgraph,
 102    * disconnecting it from other blocks as needed.
 103    *
 104    */
 105   void disconnect(gr_basic_block_sptr block);
 106
 107   /*!
 108    * \brief Disconnect a pair of gr-blocks or hierarchical blocks in internal
 109    *        flowgraph.
 110    *
 111    * This disconnects the specified input port from the specified output port
 112    * of a pair of gr-blocks or hierarchical blocks.
 113    */
 114   void disconnect(gr_basic_block_sptr src, int src_port,
 115                   gr_basic_block_sptr dst, int dst_port);
 116
 117   /*!
 118    * \brief Disconnect all connections in the internal flowgraph.
 119    *
 120    * This call removes all output port to input port connections in the internal
 121    * flowgraph.
 122    */
 123   void disconnect_all();
 124
 125   /*!
 126    * Lock a flowgraph in preparation for reconfiguration.  When an equal
 127    * number of calls to lock() and unlock() have occurred, the flowgraph
 128    * will be reconfigured.
 129    *
 130    * N.B. lock() and unlock() may not be called from a flowgraph thread
 131    * (E.g., gr_block::work method) or deadlock will occur when
 132    * reconfiguration happens.
 133    */
 134   virtual void lock();
 135
 136   /*!
 137    * Unlock a flowgraph in preparation for reconfiguration.  When an equal
 138    * number of calls to lock() and unlock() have occurred, the flowgraph
 139    * will be reconfigured.
 140    *
 141    * N.B. lock() and unlock() may not be called from a flowgraph thread
 142    * (E.g., gr_block::work method) or deadlock will occur when
 143    * reconfiguration happens.
 144    */
 145   virtual void unlock();
 146
 147   // This is a public method for ease of code organization, but should be
 148   // ignored by the user.
 149   gr_flat_flowgraph_sptr flatten() const;
 150 };
 151
 152 inline gr_hier_block2_sptr cast_to_hier_block2_sptr(gr_basic_block_sptr block) {
 153   return boost::dynamic_pointer_cast<gr_hier_block2, gr_basic_block>(block);
 154 }
 155
 156 #endif /* INCLUDED_GR_HIER_BLOCK2_H */