GNU Radio Manual and C++ API Reference  3.10.9.1
The Free & Open Software Radio Ecosystem
basic_block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2006,2008,2009,2011,2013 Free Software Foundation, Inc.
4  *
5  * This file is part of GNU Radio
6  *
7  * SPDX-License-Identifier: GPL-3.0-or-later
8  *
9  */
10 
11 #ifndef INCLUDED_GR_BASIC_BLOCK_H
12 #define INCLUDED_GR_BASIC_BLOCK_H
13 
14 #include <gnuradio/api.h>
15 #include <gnuradio/io_signature.h>
16 #include <gnuradio/logger.h>
17 #include <gnuradio/msg_accepter.h>
18 #include <gnuradio/runtime_types.h>
19 #include <gnuradio/sptr_magic.h>
20 #include <gnuradio/thread/thread.h>
21 #include <boost/thread/condition_variable.hpp>
22 #include <deque>
23 #include <functional>
24 #include <map>
25 #include <string>
26 
28 
29 namespace gr {
30 
32 {
33 private:
34  const pmt::pmt_t d_system_port = pmt::intern("system");
35 
36 public:
37  bool operator()(pmt::pmt_t const& queue_key1, pmt::pmt_t const& queue_key2) const
38  {
39  if (pmt::eqv(queue_key2, d_system_port))
40  return false;
41  else if (pmt::eqv(queue_key1, d_system_port))
42  return true;
43  else {
44  pmt::comparator cmp;
45  return cmp(queue_key1, queue_key2);
46  }
47  }
48 };
49 
50 /*!
51  * \brief The abstract base class for all signal processing blocks.
52  * \ingroup internal
53  *
54  * Basic blocks are the bare abstraction of an entity that has a
55  * name, a set of inputs and outputs, and a message queue. These
56  * are never instantiated directly; rather, this is the abstract
57  * parent class of both gr_hier_block, which is a recursive
58  * container, and block, which implements actual signal
59  * processing functions.
60  */
62  public std::enable_shared_from_this<basic_block>
63 {
64  typedef std::function<void(pmt::pmt_t)> msg_handler_t;
65 
66 private:
67  typedef std::map<pmt::pmt_t, msg_handler_t, pmt::comparator> d_msg_handlers_t;
68  d_msg_handlers_t d_msg_handlers;
69 
70  typedef std::deque<pmt::pmt_t> msg_queue_t;
71  typedef std::map<pmt::pmt_t, msg_queue_t, msg_queue_comparator> msg_queue_map_t;
72  typedef std::map<pmt::pmt_t, msg_queue_t, msg_queue_comparator>::iterator
73  msg_queue_map_itr;
74 
75  gr::thread::mutex mutex; //< protects all vars
76 
77 protected:
78  friend class flowgraph;
79  friend class flat_flowgraph; // TODO: will be redundant
80  friend class tpb_thread_body;
81 
82  enum vcolor { WHITE, GREY, BLACK };
83 
84  std::string d_name;
89  std::string d_symbol_name;
90  std::string d_symbol_alias;
92  bool d_rpc_set;
93 
94  /*! Used by blocks to access the logger system.
95  */
96  gr::logger_ptr d_logger; //! Default logger
97  gr::logger_ptr d_debug_logger; //! Verbose logger
98 
99  msg_queue_map_t msg_queue;
100  std::vector<rpcbasic_sptr> d_rpc_vars; // container for all RPC variables
101 
102  basic_block(void) {} // allows pure virtual interface sub-classes
103 
104  //! Protected constructor prevents instantiation by non-derived classes
105  basic_block(const std::string& name,
106  gr::io_signature::sptr input_signature,
107  gr::io_signature::sptr output_signature);
108 
109  //! may only be called during constructor
110  void set_input_signature(gr::io_signature::sptr iosig) { d_input_signature = iosig; }
111 
112  //! may only be called during constructor
114  {
115  d_output_signature = iosig;
116  }
117 
118  /*!
119  * \brief Allow the flowgraph to set for sorting and partitioning
120  */
121  void set_color(vcolor color) { d_color = color; }
122  vcolor color() const { return d_color; }
123 
124  /*!
125  * \brief Tests if there is a handler attached to port \p which_port
126  */
127  virtual bool has_msg_handler(pmt::pmt_t which_port)
128  {
129  return (d_msg_handlers.find(which_port) != d_msg_handlers.end());
130  }
131 
132  /*
133  * This function is called by the runtime system to dispatch messages.
134  *
135  * The thread-safety guarantees mentioned in set_msg_handler are
136  * implemented by the callers of this method.
137  */
138  virtual void dispatch_msg(pmt::pmt_t which_port, pmt::pmt_t msg)
139  {
140  // AA Update this
141  if (has_msg_handler(which_port)) { // Is there a handler?
142  d_msg_handlers[which_port](msg); // Yes, invoke it.
143  }
144  }
145 
146  // Message passing interface
148 
149  /*!
150  * \brief This is meant to be called by derived classes (e.g. block) to get
151  * a shared pointer internally. This is needed because
152  * std::enable_shared_from_this doesn't seem to work with derived classes
153  * in an inheritance hierarchy.
154  */
155  template <typename Derived>
156  std::shared_ptr<Derived> shared_from_base()
157  {
158  return std::static_pointer_cast<Derived>(shared_from_this());
159  }
160 
161 public:
163  ~basic_block() override;
164  long unique_id() const { return d_unique_id; }
165  long symbolic_id() const { return d_symbolic_id; }
166 
167  /*! The name of the block */
168  std::string name() const { return d_name; }
169 
170  /*!
171  * The sybolic name of the block, which is used in the
172  * block_registry. The name is assigned by the block's constructor
173  * and never changes during the life of the block.
174  */
175  std::string symbol_name() const { return d_symbol_name; }
176  std::string identifier() const
177  {
178  return this->name() + "(" + std::to_string(this->unique_id()) + ")";
179  }
180 
181  gr::io_signature::sptr input_signature() const { return d_input_signature; }
182  gr::io_signature::sptr output_signature() const { return d_output_signature; }
183  basic_block_sptr to_basic_block(); // Needed for Python type coercion
184 
185  /*!
186  * True if the block has an alias (see set_block_alias).
187  */
188  bool alias_set() const { return !d_symbol_alias.empty(); }
189 
190  /*!
191  * Returns the block's alias as a string.
192  */
193  std::string alias() const { return alias_set() ? d_symbol_alias : symbol_name(); }
194 
195  /*!
196  * Returns the block's alias as PMT.
197  */
198  pmt::pmt_t alias_pmt() const { return pmt::intern(alias()); }
199 
200  /*!
201  * Set's a new alias for the block; also adds an entry into the
202  * block_registry to get the block using either the alias or the
203  * original symbol name.
204  */
205  void set_block_alias(std::string name);
206 
207  // ** Message passing interface **
211  void message_port_sub(pmt::pmt_t port_id, pmt::pmt_t target);
212  void message_port_unsub(pmt::pmt_t port_id, pmt::pmt_t target);
213 
214  virtual bool message_port_is_hier(pmt::pmt_t port_id)
215  {
216  (void)port_id;
217  return false;
218  }
219  virtual bool message_port_is_hier_in(pmt::pmt_t port_id)
220  {
221  (void)port_id;
222  return false;
223  }
224  virtual bool message_port_is_hier_out(pmt::pmt_t port_id)
225  {
226  (void)port_id;
227  return false;
228  }
229 
230  /*!
231  * \brief Get input message port names.
232  *
233  * Returns the available input message ports for a block. The
234  * return object is a PMT vector that is filled with PMT symbols.
235  */
237 
238  /*!
239  * \brief Get output message port names.
240  *
241  * Returns the available output message ports for a block. The
242  * return object is a PMT vector that is filled with PMT symbols.
243  */
245 
246  /*!
247  * Accept msg, place in queue, arrange for thread to be awakened if it's not already.
248  */
249  void _post(pmt::pmt_t which_port, pmt::pmt_t msg);
250 
251  //! is the queue empty?
252  bool empty_p(pmt::pmt_t which_port)
253  {
254  if (msg_queue.find(which_port) == msg_queue.end())
255  throw std::runtime_error("port does not exist!");
256  return msg_queue[which_port].empty();
257  }
258  bool empty_p()
259  {
260  bool rv = true;
261  for (const auto& i : msg_queue) {
262  rv &= msg_queue[i.first].empty();
263  }
264  return rv;
265  }
266 
267  //! are all msg ports with handlers empty?
268  bool empty_handled_p(pmt::pmt_t which_port)
269  {
270  return (empty_p(which_port) || !has_msg_handler(which_port));
271  }
273  {
274  bool rv = true;
275  for (const auto& i : msg_queue) {
276  rv &= empty_handled_p(i.first);
277  }
278  return rv;
279  }
280 
281  //! How many messages in the queue?
282  size_t nmsgs(pmt::pmt_t which_port)
283  {
284  if (msg_queue.find(which_port) == msg_queue.end())
285  throw std::runtime_error("port does not exist!");
286  return msg_queue[which_port].size();
287  }
288 
289  //| Acquires and release the mutex
291  /*!
292  * \returns returns pmt at head of queue or pmt::pmt_t() if empty.
293  */
295 
296  msg_queue_t::iterator get_iterator(pmt::pmt_t which_port)
297  {
298  return msg_queue[which_port].begin();
299  }
300 
301  void erase_msg(pmt::pmt_t which_port, msg_queue_t::iterator it)
302  {
303  msg_queue[which_port].erase(it);
304  }
305 
306  virtual bool has_msg_port(pmt::pmt_t which_port)
307  {
308  if (msg_queue.find(which_port) != msg_queue.end()) {
309  return true;
310  }
311  if (pmt::dict_has_key(d_message_subscribers, which_port)) {
312  return true;
313  }
314  return false;
315  }
316 
317  const msg_queue_map_t& get_msg_map(void) const { return msg_queue; }
318 
319 #ifdef GR_CTRLPORT
320  /*!
321  * \brief Add an RPC variable (get or set).
322  *
323  * Using controlport, we create new getters/setters and need to
324  * store them. Each block has a vector to do this, and these never
325  * need to be accessed again once they are registered with the RPC
326  * backend. This function takes a
327  * std::shared_sptr<rpcbasic_base> so that when the block is
328  * deleted, all RPC registered variables are cleaned up.
329  *
330  * \param s an rpcbasic_sptr of the new RPC variable register to store.
331  */
332  void add_rpc_variable(rpcbasic_sptr s) { d_rpc_vars.push_back(s); }
333 #endif /* GR_CTRLPORT */
334 
335  /*!
336  * \brief Set up the RPC registered variables.
337  *
338  * This must be overloaded by a block that wants to use
339  * controlport. This is where rpcbasic_register_{get,set} pointers
340  * are created, which then get wrapped as shared pointers
341  * (rpcbasic_sptr(...)) and stored using add_rpc_variable.
342  */
343  virtual void setup_rpc(){};
344 
345  /*!
346  * \brief Ask if this block has been registered to the RPC.
347  *
348  * We can only register a block once, so we use this to protect us
349  * from calling it multiple times.
350  */
351  bool is_rpc_set() { return d_rpc_set; }
352 
353  /*!
354  * \brief When the block is registered with the RPC, set this.
355  */
356  void rpc_set() { d_rpc_set = true; }
357 
358  /*!
359  * \brief Confirm that ninputs and noutputs is an acceptable combination.
360  *
361  * \param ninputs number of input streams connected
362  * \param noutputs number of output streams connected
363  *
364  * \returns true if this is a valid configuration for this block.
365  *
366  * This function is called by the runtime system whenever the
367  * topology changes. Most classes do not need to override this.
368  * This check is in addition to the constraints specified by the
369  * input and output gr::io_signatures.
370  */
371  virtual bool check_topology(int ninputs, int noutputs)
372  {
373  (void)ninputs;
374  (void)noutputs;
375  return true;
376  }
377 
378  /*!
379  * \brief Set the callback that is fired when messages are available.
380  *
381  * \p msg_handler can be any kind of function pointer or function object
382  * that has the signature:
383  * <pre>
384  * void msg_handler(pmt::pmt msg);
385  * </pre>
386  *
387  * (You may want to use boost::bind to massage your callable into
388  * the correct form. See gr::blocks::nop for an example that sets
389  * up a class method as the callback.)
390  *
391  * Blocks that desire to handle messages must call this method in
392  * their constructors to register the handler that will be invoked
393  * when messages are available.
394  *
395  * If the block inherits from block, the runtime system will
396  * ensure that msg_handler is called in a thread-safe manner, such
397  * that work and msg_handler will never be called concurrently.
398  * This allows msg_handler to update state variables without
399  * having to worry about thread-safety issues with work,
400  * general_work or another invocation of msg_handler.
401  *
402  * If the block inherits from hier_block2, the runtime system
403  * will ensure that no reentrant calls are made to msg_handler.
404  */
405  template <typename T>
407  {
408  if (msg_queue.find(which_port) == msg_queue.end()) {
409  throw std::runtime_error(
410  "attempt to set_msg_handler() on bad input message port!");
411  }
412  d_msg_handlers[which_port] = msg_handler_t(msg_handler);
413  }
414 
415  virtual void set_processor_affinity(const std::vector<int>& mask) = 0;
416 
417  virtual void unset_processor_affinity() = 0;
418 
419  virtual std::vector<int> processor_affinity() = 0;
420 
421  virtual void set_log_level(const std::string& level) = 0;
422 
423  virtual std::string log_level() = 0;
424 };
425 
426 inline bool operator<(basic_block_sptr lhs, basic_block_sptr rhs)
427 {
428  return lhs->unique_id() < rhs->unique_id();
429 }
430 
431 typedef std::vector<basic_block_sptr> basic_block_vector_t;
432 typedef std::vector<basic_block_sptr>::iterator basic_block_viter_t;
433 
435 
436 inline std::ostream& operator<<(std::ostream& os, basic_block_sptr basic_block)
437 {
438  os << basic_block->identifier();
439  return os;
440 }
441 
442 } /* namespace gr */
443 
444 #endif /* INCLUDED_GR_BASIC_BLOCK_H */
The abstract base class for all signal processing blocks.
Definition: basic_block.h:63
gr::io_signature::sptr input_signature() const
Definition: basic_block.h:181
virtual void set_log_level(const std::string &level)=0
bool empty_handled_p(pmt::pmt_t which_port)
are all msg ports with handlers empty?
Definition: basic_block.h:268
bool is_rpc_set()
Ask if this block has been registered to the RPC.
Definition: basic_block.h:351
gr::logger_ptr d_debug_logger
Default logger.
Definition: basic_block.h:97
pmt::pmt_t message_subscribers(pmt::pmt_t port)
virtual bool message_port_is_hier_out(pmt::pmt_t port_id)
Definition: basic_block.h:224
void set_color(vcolor color)
Allow the flowgraph to set for sorting and partitioning.
Definition: basic_block.h:121
std::string d_symbol_alias
Definition: basic_block.h:90
long unique_id() const
Definition: basic_block.h:164
msg_queue_t::iterator get_iterator(pmt::pmt_t which_port)
Definition: basic_block.h:296
void message_port_register_in(pmt::pmt_t port_id)
void set_input_signature(gr::io_signature::sptr iosig)
may only be called during constructor
Definition: basic_block.h:110
basic_block(const std::string &name, gr::io_signature::sptr input_signature, gr::io_signature::sptr output_signature)
Protected constructor prevents instantiation by non-derived classes.
void message_port_pub(pmt::pmt_t port_id, pmt::pmt_t msg)
size_t nmsgs(pmt::pmt_t which_port)
How many messages in the queue?
Definition: basic_block.h:282
virtual void set_processor_affinity(const std::vector< int > &mask)=0
virtual bool message_port_is_hier_in(pmt::pmt_t port_id)
Definition: basic_block.h:219
gr::logger_ptr d_logger
Definition: basic_block.h:96
msg_queue_map_t msg_queue
Verbose logger.
Definition: basic_block.h:99
basic_block(void)
Definition: basic_block.h:102
~basic_block() override
long d_symbolic_id
Definition: basic_block.h:88
bool empty_handled_p()
Definition: basic_block.h:272
virtual std::string log_level()=0
void set_output_signature(gr::io_signature::sptr iosig)
may only be called during constructor
Definition: basic_block.h:113
std::string identifier() const
Definition: basic_block.h:176
long symbolic_id() const
Definition: basic_block.h:165
pmt::pmt_t alias_pmt() const
Definition: basic_block.h:198
virtual void setup_rpc()
Set up the RPC registered variables.
Definition: basic_block.h:343
void set_msg_handler(pmt::pmt_t which_port, T msg_handler)
Set the callback that is fired when messages are available.
Definition: basic_block.h:406
basic_block_sptr to_basic_block()
gr::io_signature::sptr d_output_signature
Definition: basic_block.h:86
gr::io_signature::sptr d_input_signature
Definition: basic_block.h:85
virtual bool message_port_is_hier(pmt::pmt_t port_id)
Definition: basic_block.h:214
long d_unique_id
Definition: basic_block.h:87
virtual bool has_msg_port(pmt::pmt_t which_port)
Definition: basic_block.h:306
bool d_rpc_set
Definition: basic_block.h:92
virtual void dispatch_msg(pmt::pmt_t which_port, pmt::pmt_t msg)
Definition: basic_block.h:138
virtual std::vector< int > processor_affinity()=0
std::string symbol_name() const
Definition: basic_block.h:175
std::string alias() const
Definition: basic_block.h:193
void _post(pmt::pmt_t which_port, pmt::pmt_t msg)
bool alias_set() const
Definition: basic_block.h:188
void message_port_register_out(pmt::pmt_t port_id)
void rpc_set()
When the block is registered with the RPC, set this.
Definition: basic_block.h:356
virtual void unset_processor_affinity()=0
vcolor
Definition: basic_block.h:82
virtual bool has_msg_handler(pmt::pmt_t which_port)
Tests if there is a handler attached to port which_port.
Definition: basic_block.h:127
virtual bool check_topology(int ninputs, int noutputs)
Confirm that ninputs and noutputs is an acceptable combination.
Definition: basic_block.h:371
void insert_tail(pmt::pmt_t which_port, pmt::pmt_t msg)
void erase_msg(pmt::pmt_t which_port, msg_queue_t::iterator it)
Definition: basic_block.h:301
void set_block_alias(std::string name)
void message_port_unsub(pmt::pmt_t port_id, pmt::pmt_t target)
pmt::pmt_t message_ports_out()
Get output message port names.
std::string d_name
Definition: basic_block.h:84
void message_port_sub(pmt::pmt_t port_id, pmt::pmt_t target)
std::shared_ptr< Derived > shared_from_base()
This is meant to be called by derived classes (e.g. block) to get a shared pointer internally....
Definition: basic_block.h:156
gr::io_signature::sptr output_signature() const
Definition: basic_block.h:182
std::vector< rpcbasic_sptr > d_rpc_vars
Definition: basic_block.h:100
vcolor color() const
Definition: basic_block.h:122
const msg_queue_map_t & get_msg_map(void) const
Definition: basic_block.h:317
pmt::pmt_t message_ports_in()
Get input message port names.
bool empty_p(pmt::pmt_t which_port)
is the queue empty?
Definition: basic_block.h:252
bool empty_p()
Definition: basic_block.h:258
pmt::pmt_t d_message_subscribers
Definition: basic_block.h:147
std::string name() const
Definition: basic_block.h:168
std::string d_symbol_name
Definition: basic_block.h:89
pmt::pmt_t delete_head_nowait(pmt::pmt_t which_port)
vcolor d_color
Definition: basic_block.h:91
Class representing a directed, acyclic graph of basic blocks.
Definition: flowgraph.h:150
std::shared_ptr< io_signature > sptr
Definition: io_signature.h:52
Accepts messages and inserts them into a message queue, then notifies subclass gr::basic_block there ...
Definition: msg_accepter.h:25
abstract class of message handlers
Definition: msg_handler.h:27
Definition: basic_block.h:32
bool operator()(pmt::pmt_t const &queue_key1, pmt::pmt_t const &queue_key2) const
Definition: basic_block.h:37
thread-safe message queue
Definition: msg_queue.h:25
Provide a comparator function object to allow pmt use in stl types.
Definition: pmt.h:991
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:18
GR_RUNTIME_API const pmt::pmt_t msg()
boost::mutex mutex
Definition: thread.h:37
GNU Radio logging wrapper.
Definition: basic_block.h:29
std::shared_ptr< logger > logger_ptr
Definition: logger.h:250
std::vector< basic_block_sptr > basic_block_vector_t
Definition: basic_block.h:431
bool operator<(basic_block_sptr lhs, basic_block_sptr rhs)
Definition: basic_block.h:426
std::vector< basic_block_sptr >::iterator basic_block_viter_t
Definition: basic_block.h:432
GR_RUNTIME_API long basic_block_ncurrently_allocated()
std::ostream & operator<<(std::ostream &os, basic_block_sptr basic_block)
Definition: basic_block.h:436
PMT_API bool dict_has_key(const pmt_t &dict, const pmt_t &key)
Return true if key exists in dict.
PMT_API bool eqv(const pmt_t &x, const pmt_t &y)
Return true if x and y should normally be regarded as the same object, else false.
PMT_API pmt_t intern(const std::string &s)
Alias for pmt_string_to_symbol.
std::shared_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting).
Definition: pmt.h:83