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