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
top_block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2007-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_TOP_BLOCK_H
24 #define INCLUDED_GR_TOP_BLOCK_H
25 
26 #include <gnuradio/api.h>
27 #include <gnuradio/hier_block2.h>
28 
29 namespace gr {
30 
31  class top_block_impl;
32 
33  GR_RUNTIME_API top_block_sptr make_top_block(const std::string &name);
34 
35  /*!
36  *\brief Top-level hierarchical block representing a flowgraph
37  * \ingroup container_blk
38  */
40  {
41  private:
42  friend GR_RUNTIME_API top_block_sptr
43  make_top_block(const std::string &name);
44 
45  top_block_impl *d_impl;
46 
47  protected:
48  top_block(const std::string &name);
49 
50  public:
51  ~top_block();
52 
53  /*!
54  * \brief The simple interface to running a flowgraph.
55  *
56  * Calls start() then wait(). Used to run a flowgraph that will
57  * stop on its own, or when another thread will call stop().
58  *
59  * \param max_noutput_items the maximum number of output items
60  * allowed for any block in the flowgraph. This passes through to
61  * the start function; see that function for more details.
62  */
63  void run(int max_noutput_items=100000000);
64 
65  /*!
66  * Start the contained flowgraph. Creates one or more threads to
67  * execute the flow graph. Returns to the caller once the threads
68  * are created. Calling start() on a top_block that is already
69  * started IS an error.
70  *
71  * \param max_noutput_items the maximum number of output items
72  * allowed for any block in the flowgraph; the noutput_items can
73  * always be less than this, but this will cap it as a
74  * maximum. Use this to adjust the maximum latency a flowgraph can
75  * exhibit.
76  */
77  void start(int max_noutput_items=100000000);
78 
79  /*!
80  * Stop the running flowgraph. Notifies each thread created by the
81  * scheduler to shutdown, then returns to caller. Calling stop()
82  * on a top_block that is already stopped IS NOT an error.
83  */
84  void stop();
85 
86  /*!
87  * Wait for a flowgraph to complete. Flowgraphs complete when
88  * either (1) all blocks indicate that they are done (typically
89  * only when using blocks.file_source, or blocks.head, or (2)
90  * after stop() has been called to request shutdown. Calling wait
91  * on a top_block that is not running IS NOT an error (wait
92  * returns w/o blocking).
93  */
94  void wait();
95 
96  /*!
97  * Lock a flowgraph in preparation for reconfiguration. When an
98  * equal number of calls to lock() and unlock() have occurred, the
99  * flowgraph will be reconfigured.
100  *
101  * N.B. lock() and unlock() may not be called from a flowgraph
102  * thread (E.g., block::work method) or deadlock will occur
103  * when reconfiguration happens.
104  */
105  virtual void lock();
106 
107  /*!
108  * Unlock a flowgraph in preparation for reconfiguration. When an
109  * equal number of calls to lock() and unlock() have occurred, the
110  * flowgraph will be reconfigured.
111  *
112  * N.B. lock() and unlock() may not be called from a flowgraph thread
113  * (E.g., block::work method) or deadlock will occur when
114  * reconfiguration happens.
115  */
116  virtual void unlock();
117 
118  /*!
119  * Returns a string that lists the edge connections in the
120  * flattened flowgraph.
121  */
122  std::string edge_list();
123 
124  /*!
125  * Returns a string that lists the msg edge connections in the
126  * flattened flowgraph.
127  */
128  std::string msg_edge_list();
129 
130  /*!
131  * Displays flattened flowgraph edges and block connectivity
132  */
133  void dump();
134 
135  //! Get the number of max noutput_items in the flowgraph
136  int max_noutput_items();
137 
138  //! Set the maximum number of noutput_items in the flowgraph
139  void set_max_noutput_items(int nmax);
140 
141  top_block_sptr to_top_block(); // Needed for Python type coercion
142 
143  void setup_rpc();
144  };
145 
146  inline top_block_sptr cast_to_top_block_sptr(basic_block_sptr block) {
147  return boost::dynamic_pointer_cast<top_block, basic_block>(block);
148  }
149 
150 } /* namespce gr */
151 
152 #endif /* INCLUDED_GR_TOP_BLOCK_H */
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:30
Include this header to use the message passing features.
Definition: logger.h:131
The abstract base class for all signal processing blocks.Basic blocks are the bare abstraction of an ...
Definition: basic_block.h:58
The abstract base class for all 'terminal' processing blocks.A signal processing flow is constructed ...
Definition: block.h:60
Top-level hierarchical block representing a flowgraph.
Definition: top_block.h:39
Hierarchical container class for gr::block's and gr::hier_block2's.
Definition: hier_block2.h:46
GR_RUNTIME_API top_block_sptr make_top_block(const std::string &name)