GNU Radio Manual and C++ API Reference  3.7.9.2
The Free & Open Software Radio Ecosystem
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
hier_block2.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2006-2009,2013 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 
23 #ifndef INCLUDED_GR_RUNTIME_HIER_BLOCK2_H
24 #define INCLUDED_GR_RUNTIME_HIER_BLOCK2_H
25 
26 #include <gnuradio/api.h>
27 #include <gnuradio/basic_block.h>
28 
29 namespace gr {
30 
31  /*!
32  * \brief public constructor for hier_block2
33  */
34  GR_RUNTIME_API hier_block2_sptr
35  make_hier_block2(const std::string &name,
36  gr::io_signature::sptr input_signature,
37  gr::io_signature::sptr output_signature);
38 
39  class hier_block2_detail;
40 
41  /*!
42  * \brief Hierarchical container class for gr::block's and gr::hier_block2's
43  * \ingroup container_blk
44  * \ingroup base_blk
45  */
47  {
48  private:
49  friend class hier_block2_detail;
50  friend GR_RUNTIME_API hier_block2_sptr
51  make_hier_block2(const std::string &name,
52  gr::io_signature::sptr input_signature,
53  gr::io_signature::sptr output_signature);
54 
55  /*!
56  * \brief Private implementation details of gr::hier_block2
57  */
58  hier_block2_detail *d_detail;
59 
60 
61  protected:
62  hier_block2(void) {} // allows pure virtual interface sub-classes
63  hier_block2(const std::string &name,
64  gr::io_signature::sptr input_signature,
65  gr::io_signature::sptr output_signature);
66 
67  public:
68  virtual ~hier_block2();
69 
70  /*!
71  * \brief typedef for object returned from self().
72  *
73  * This type is only guaranteed to be passable to connect and
74  * disconnect. No other assumptions should be made about it.
75  */
76  typedef basic_block_sptr opaque_self;
77 
78  /*!
79  * \brief Return an object, representing the current block, which
80  * can be passed to connect.
81  *
82  * The returned object may only be used as an argument to connect
83  * or disconnect. Any other use of self() results in unspecified
84  * (erroneous) behavior.
85  */
86  opaque_self self();
87 
88  /*!
89  * \brief Add a stand-alone (possibly hierarchical) block to
90  * internal graph
91  *
92  * This adds a gr-block or hierarchical block to the internal
93  * graph without wiring it to anything else.
94  */
95  void connect(basic_block_sptr block);
96 
97  /*!
98  * \brief Add gr-blocks or hierarchical blocks to internal graph
99  * and wire together
100  *
101  * This adds (if not done earlier by another connect) a pair of
102  * gr-blocks or hierarchical blocks to the internal flowgraph, and
103  * wires the specified output port to the specified input port.
104  */
105  void connect(basic_block_sptr src, int src_port,
106  basic_block_sptr dst, int dst_port);
107 
108  /*!
109  * \brief Add gr-blocks or hierarchical blocks to internal graph
110  * and wire together
111  *
112  * This adds (if not done earlier by another connect) a pair of
113  * gr-blocks or hierarchical blocks to the internal message port
114  * subscription
115  */
116  void msg_connect(basic_block_sptr src, pmt::pmt_t srcport,
117  basic_block_sptr dst, pmt::pmt_t dstport);
118  void msg_connect(basic_block_sptr src, std::string srcport,
119  basic_block_sptr dst, std::string dstport);
120  void msg_disconnect(basic_block_sptr src, pmt::pmt_t srcport,
121  basic_block_sptr dst, pmt::pmt_t dstport);
122  void msg_disconnect(basic_block_sptr src, std::string srcport,
123  basic_block_sptr dst, std::string dstport);
124 
125  /*!
126  * \brief Remove a gr-block or hierarchical block from the
127  * internal flowgraph.
128  *
129  * This removes a gr-block or hierarchical block from the internal
130  * flowgraph, disconnecting it from other blocks as needed.
131  */
132  void disconnect(basic_block_sptr block);
133 
134  /*!
135  * \brief Disconnect a pair of gr-blocks or hierarchical blocks in
136  * internal flowgraph.
137  *
138  * This disconnects the specified input port from the specified
139  * output port of a pair of gr-blocks or hierarchical blocks.
140  */
141  void disconnect(basic_block_sptr src, int src_port,
142  basic_block_sptr dst, int dst_port);
143 
144  /*!
145  * \brief Disconnect all connections in the internal flowgraph.
146  *
147  * This call removes all output port to input port connections in
148  * the internal flowgraph.
149  */
150  void disconnect_all();
151 
152  /*!
153  * Lock a flowgraph in preparation for reconfiguration. When an
154  * equal number of calls to lock() and unlock() have occurred, the
155  * flowgraph will be reconfigured.
156  *
157  * N.B. lock() and unlock() may not be called from a flowgraph
158  * thread (E.g., gr::block::work method) or deadlock will occur
159  * when reconfiguration happens.
160  */
161  virtual void lock();
162 
163  /*!
164  * Unlock a flowgraph in preparation for reconfiguration. When an
165  * equal number of calls to lock() and unlock() have occurred, the
166  * flowgraph will be reconfigured.
167  *
168  * N.B. lock() and unlock() may not be called from a flowgraph
169  * thread (E.g., gr::block::work method) or deadlock will occur
170  * when reconfiguration happens.
171  */
172  virtual void unlock();
173 
174  /*!
175  * \brief Returns max buffer size (itemcount) on output port \p i.
176  */
177  int max_output_buffer(size_t port=0);
178 
179  /*!
180  * \brief Sets max buffer size (itemcount) on all output ports.
181  */
182  void set_max_output_buffer(int max_output_buffer);
183 
184  /*!
185  * \brief Sets max buffer size (itemcount) on output port \p port.
186  */
187  void set_max_output_buffer(size_t port, int max_output_buffer);
188 
189  /*!
190  * \brief Returns min buffer size (itemcount) on output port \p i.
191  */
192  int min_output_buffer(size_t port=0);
193 
194  /*!
195  * \brief Sets min buffer size (itemcount) on all output ports.
196  */
197  void set_min_output_buffer(int min_output_buffer);
198 
199  /*!
200  * \brief Sets min buffer size (itemcount) on output port \p port.
201  */
202  void set_min_output_buffer(size_t port, int min_output_buffer);
203 
204 
205  // This is a public method for ease of code organization, but should be
206  // ignored by the user.
207  flat_flowgraph_sptr flatten() const;
208 
209  hier_block2_sptr to_hier_block2(); // Needed for Python type coercion
210 
211  bool has_msg_port(pmt::pmt_t which_port) {
212  return message_port_is_hier(which_port) || basic_block::has_msg_port(which_port);
213  }
214 
216  return message_port_is_hier_in(port_id) || message_port_is_hier_out(port_id);
217  }
218 
220  return pmt::list_has(hier_message_ports_in, port_id);
221  }
222 
224  return pmt::list_has(hier_message_ports_out, port_id);
225  }
226 
229 
231  if(pmt::list_has(hier_message_ports_in, port_id))
232  throw std::invalid_argument("hier msg in port by this name already registered");
233  if(msg_queue.find(port_id) != msg_queue.end())
234  throw std::invalid_argument("block already has a primitive input port by this name");
235  hier_message_ports_in = pmt::list_add(hier_message_ports_in, port_id);
236  }
237 
239  if(pmt::list_has(hier_message_ports_out, port_id))
240  throw std::invalid_argument("hier msg out port by this name already registered");
241  if(pmt::dict_has_key(d_message_subscribers, port_id))
242  throw std::invalid_argument("block already has a primitive output port by this name");
243  hier_message_ports_out = pmt::list_add(hier_message_ports_out, port_id);
244  }
245 
246  /*!
247  * \brief Set the affinity of all blocks in hier_block2 to processor core \p n.
248  *
249  * \param mask a vector of ints of the core numbers available to this block.
250  */
251  void set_processor_affinity(const std::vector<int> &mask);
252 
253  /*!
254  * \brief Remove processor affinity for all blocks in hier_block2.
255  */
256  void unset_processor_affinity();
257 
258  /*!
259  * \brief Get the current processor affinity.
260  *
261  * \details This returns the processor affinity value for the first
262  * block in the hier_block2's list of blocks with the assumption
263  * that they have always only been set through the hier_block2's
264  * interface. If any block has been individually set, then this
265  * call could be misleading.
266  */
267  std::vector<int> processor_affinity();
268 
269  /*!
270  * \brief Get if all block min buffers should be set.
271  *
272  * \details this returns whether all the block min output buffers
273  * should be set or just the block ports connected to the hier ports.
274  */
275  bool all_min_output_buffer_p(void);
276 
277  /*!
278  * \brief Get if all block max buffers should be set.
279  *
280  * \details this returns whether all the block max output buffers
281  * should be set or just the block ports connected to the hier ports.
282  */
283  bool all_max_output_buffer_p(void);
284  };
285 
286  /*!
287  * \brief Return hierarchical block's flow graph represented in dot language
288  */
289  GR_RUNTIME_API std::string dot_graph(hier_block2_sptr hierblock2);
290 
291  inline hier_block2_sptr cast_to_hier_block2_sptr(basic_block_sptr block) {
292  return boost::dynamic_pointer_cast<hier_block2, basic_block>(block);
293  }
294 
295 } /* namespace gr */
296 
297 #endif /* INCLUDED_GR_RUNTIME_HIER_BLOCK2_H */
boost::shared_ptr< io_signature > sptr
Definition: io_signature.h:45
void message_port_register_hier_out(pmt::pmt_t port_id)
Definition: hier_block2.h:238
bool message_port_is_hier(pmt::pmt_t port_id)
Definition: hier_block2.h:215
PMT_API bool list_has(pmt_t list, const pmt_t &item)
Return bool of list contains item.
void message_port_register_hier_in(pmt::pmt_t port_id)
Definition: hier_block2.h:230
bool has_msg_port(pmt::pmt_t which_port)
Definition: hier_block2.h:211
virtual bool has_msg_port(pmt::pmt_t which_port)
Definition: basic_block.h:270
basic_block_sptr opaque_self
typedef for object returned from self().
Definition: hier_block2.h:76
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:30
thread-safe message queue
Definition: msg_queue.h:36
Include this header to use the message passing features.
Definition: logger.h:131
GR_RUNTIME_API std::string dot_graph(hier_block2_sptr hierblock2)
Return hierarchical block's flow graph represented in dot language.
The abstract base class for all signal processing blocks.Basic blocks are the bare abstraction of an ...
Definition: basic_block.h:58
bool message_port_is_hier_in(pmt::pmt_t port_id)
Definition: hier_block2.h:219
bool message_port_is_hier_out(pmt::pmt_t port_id)
Definition: hier_block2.h:223
hier_block2(void)
Definition: hier_block2.h:62
pmt::pmt_t hier_message_ports_in
Definition: hier_block2.h:227
pmt::pmt_t hier_message_ports_out
Definition: hier_block2.h:228
PMT_API pmt_t list_add(pmt_t list, const pmt_t &item)
Return list with item added to it.
PMT_API bool dict_has_key(const pmt_t &dict, const pmt_t &key)
Return true if key exists in dict.
boost::intrusive_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting). See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
Definition: pmt.h:56
The abstract base class for all 'terminal' processing blocks.A signal processing flow is constructed ...
Definition: block.h:60
GR_RUNTIME_API hier_block2_sptr make_hier_block2(const std::string &name, gr::io_signature::sptr input_signature, gr::io_signature::sptr output_signature)
public constructor for hier_block2
Hierarchical container class for gr::block's and gr::hier_block2's.
Definition: hier_block2.h:46