GNU Radio C++ API
gr_hier_block2.h
Go to the documentation of this file.
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_core_api.h>
26 #include <gr_basic_block.h>
27 
28 /*!
29  * \brief public constructor for gr_hier_block2
30 
31  */
33  gr_io_signature_sptr input_signature,
34  gr_io_signature_sptr output_signature);
35 
37 
38 /*!
39  * \brief Hierarchical container class for gr_block's and gr_hier_block2's
40  * \ingroup container_blk
41  * \ingroup base_blk
42  *
43  */
45 {
46 private:
47  friend class gr_hier_block2_detail;
48  friend GR_CORE_API gr_hier_block2_sptr gr_make_hier_block2(const std::string &name,
49  gr_io_signature_sptr input_signature,
50  gr_io_signature_sptr output_signature);
51 
52  /*!
53  * \brief Private implementation details of gr_hier_block2
54  */
55  gr_hier_block2_detail *d_detail;
56 
57 protected:
58  gr_hier_block2(const std::string &name,
59  gr_io_signature_sptr input_signature,
60  gr_io_signature_sptr output_signature);
61 
62 public:
63  virtual ~gr_hier_block2();
64 
65  /*!
66  * \brief typedef for object returned from self().
67  *
68  * This type is only guaranteed to be passable to connect and disconnect.
69  * No other assumptions should be made about it.
70  */
72 
73  /*!
74  * \brief Return an object, representing the current block, which can be passed to connect.
75  *
76  * The returned object may only be used as an argument to connect or disconnect.
77  * Any other use of self() results in unspecified (erroneous) behavior.
78  */
79  opaque_self self();
80 
81  /*!
82  * \brief Add a stand-alone (possibly hierarchical) block to internal graph
83  *
84  * This adds a gr-block or hierarchical block to the internal graph
85  * without wiring it to anything else.
86  */
87  void connect(gr_basic_block_sptr block);
88 
89  /*!
90  * \brief Add gr-blocks or hierarchical blocks to internal graph and wire together
91  *
92  * This adds (if not done earlier by another connect) a pair of gr-blocks or
93  * hierarchical blocks to the internal flowgraph, and wires the specified output
94  * port to the specified input port.
95  */
96  void connect(gr_basic_block_sptr src, int src_port,
97  gr_basic_block_sptr dst, int dst_port);
98 
99  /*!
100  * \brief Remove a gr-block or hierarchical block from the internal flowgraph.
101  *
102  * This removes a gr-block or hierarchical block from the internal flowgraph,
103  * disconnecting it from other blocks as needed.
104  *
105  */
106  void disconnect(gr_basic_block_sptr block);
107 
108  /*!
109  * \brief Disconnect a pair of gr-blocks or hierarchical blocks in internal
110  * flowgraph.
111  *
112  * This disconnects the specified input port from the specified output port
113  * of a pair of gr-blocks or hierarchical blocks.
114  */
115  void disconnect(gr_basic_block_sptr src, int src_port,
116  gr_basic_block_sptr dst, int dst_port);
117 
118  /*!
119  * \brief Disconnect all connections in the internal flowgraph.
120  *
121  * This call removes all output port to input port connections in the internal
122  * flowgraph.
123  */
124  void disconnect_all();
125 
126  /*!
127  * Lock a flowgraph in preparation for reconfiguration. When an equal
128  * number of calls to lock() and unlock() have occurred, the flowgraph
129  * will be reconfigured.
130  *
131  * N.B. lock() and unlock() may not be called from a flowgraph thread
132  * (E.g., gr_block::work method) or deadlock will occur when
133  * reconfiguration happens.
134  */
135  virtual void lock();
136 
137  /*!
138  * Unlock a flowgraph in preparation for reconfiguration. When an equal
139  * number of calls to lock() and unlock() have occurred, the flowgraph
140  * will be reconfigured.
141  *
142  * N.B. lock() and unlock() may not be called from a flowgraph thread
143  * (E.g., gr_block::work method) or deadlock will occur when
144  * reconfiguration happens.
145  */
146  virtual void unlock();
147 
148  // This is a public method for ease of code organization, but should be
149  // ignored by the user.
150  gr_flat_flowgraph_sptr flatten() const;
151 
152  gr_hier_block2_sptr to_hier_block2(); // Needed for Python/Guile type coercion
153 };
154 
155 inline gr_hier_block2_sptr cast_to_hier_block2_sptr(gr_basic_block_sptr block) {
156  return boost::dynamic_pointer_cast<gr_hier_block2, gr_basic_block>(block);
157 }
158 
159 #endif /* INCLUDED_GR_HIER_BLOCK2_H */