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