GNU Radio 3.6.5.1 C++ API
gr_top_block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2007,2008,2009 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 <gr_core_api.h>
27 #include <gr_hier_block2.h>
28 
29 class gr_top_block_impl;
30 
31 GR_CORE_API gr_top_block_sptr gr_make_top_block(const std::string &name);
32 
33 /*!
34  *\brief Top-level hierarchical block representing a flowgraph
35  * \ingroup container_blk
36  *
37  */
39 {
40 private:
41  friend GR_CORE_API gr_top_block_sptr gr_make_top_block(const std::string &name);
42 
43  gr_top_block_impl *d_impl;
44 
45 protected:
46  gr_top_block(const std::string &name);
47 
48 public:
49  ~gr_top_block();
50 
51  /*!
52  * \brief The simple interface to running a flowgraph.
53  *
54  * Calls start() then wait(). Used to run a flowgraph that will stop
55  * on its own, or when another thread will call stop().
56  *
57  * \param max_noutput_items the maximum number of output items
58  * allowed for any block in the flowgraph. This passes through to
59  * the start function; see that function for more details.
60  */
61  void run(int max_noutput_items=100000);
62 
63  /*!
64  * Start the contained flowgraph. Creates one or more threads to
65  * execute the flow graph. Returns to the caller once the threads
66  * are created. Calling start() on a top_block that is already
67  * started IS an error.
68  *
69  * \param max_noutput_items the maximum number of output items
70  * allowed for any block in the flowgraph; the noutput_items can
71  * always be less than this, but this will cap it as a maximum. Use
72  * this to adjust the maximum latency a flowgraph can exhibit.
73  */
74  void start(int max_noutput_items=100000);
75 
76  /*!
77  * Stop the running flowgraph. Notifies each thread created by the
78  * scheduler to shutdown, then returns to caller. Calling stop() on
79  * a top_block that is already stopped IS NOT an error.
80  */
81  void stop();
82 
83  /*!
84  * Wait for a flowgraph to complete. Flowgraphs complete when
85  * either (1) all blocks indicate that they are done (typically only
86  * when using gr.file_source, or gr.head, or (2) after stop() has been
87  * called to request shutdown. Calling wait on a top_block that is
88  * not running IS NOT an error (wait returns w/o blocking).
89  */
90  void wait();
91 
92  /*!
93  * Lock a flowgraph in preparation for reconfiguration. When an equal
94  * number of calls to lock() and unlock() have occurred, the flowgraph
95  * will be reconfigured.
96  *
97  * N.B. lock() and unlock() may not be called from a flowgraph thread
98  * (E.g., gr_block::work method) or deadlock will occur when
99  * reconfiguration happens.
100  */
101  virtual void lock();
102 
103  /*!
104  * Unlock a flowgraph in preparation for reconfiguration. When an equal
105  * number of calls to lock() and unlock() have occurred, the flowgraph
106  * will be reconfigured.
107  *
108  * N.B. lock() and unlock() may not be called from a flowgraph thread
109  * (E.g., gr_block::work method) or deadlock will occur when
110  * reconfiguration happens.
111  */
112  virtual void unlock();
113 
114  /*!
115  * Displays flattened flowgraph edges and block connectivity
116  */
117  void dump();
118 
119  //! Get the number of max noutput_items in the flowgraph
120  int max_noutput_items();
121 
122  //! Set the maximum number of noutput_items in the flowgraph
123  void set_max_noutput_items(int nmax);
124 
125  gr_top_block_sptr to_top_block(); // Needed for Python type coercion
126 };
127 
128 inline gr_top_block_sptr cast_to_top_block_sptr(gr_basic_block_sptr block) {
129  return boost::dynamic_pointer_cast<gr_top_block, gr_basic_block>(block);
130 }
131 
132 
133 #endif /* INCLUDED_GR_TOP_BLOCK_H */