GNU Radio 3.5.1 C++ API
gr_top_block.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2007,2008,2009 Free Software Foundation, Inc.
00004  * 
00005  * This file is part of GNU Radio
00006  * 
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  * 
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  * 
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef INCLUDED_GR_TOP_BLOCK_H
00024 #define INCLUDED_GR_TOP_BLOCK_H
00025 
00026 #include <gr_core_api.h>
00027 #include <gr_hier_block2.h>
00028 
00029 class gr_top_block_impl;
00030 
00031 GR_CORE_API gr_top_block_sptr gr_make_top_block(const std::string &name);
00032 
00033 /*!
00034  *\brief Top-level hierarchical block representing a flowgraph
00035  * \ingroup container_blk
00036  *
00037  */
00038 class GR_CORE_API gr_top_block : public gr_hier_block2
00039 {
00040 private:
00041   friend GR_CORE_API gr_top_block_sptr gr_make_top_block(const std::string &name);
00042 
00043   gr_top_block_impl *d_impl;
00044 
00045 protected:
00046   gr_top_block(const std::string &name);
00047     
00048 public:
00049   ~gr_top_block();
00050 
00051   /*!
00052    * \brief The simple interface to running a flowgraph.
00053    *
00054    * Calls start() then wait().  Used to run a flowgraph that will stop
00055    * on its own, or when another thread will call stop().
00056    *
00057    * \param max_noutput_items the maximum number of output items
00058    * allowed for any block in the flowgraph. This passes through to
00059    * the start function; see that function for more details.
00060    */
00061   void run(int max_noutput_items=100000);
00062 
00063   /*!
00064    * Start the contained flowgraph.  Creates one or more threads to
00065    * execute the flow graph.  Returns to the caller once the threads
00066    * are created.  Calling start() on a top_block that is already
00067    * started IS an error.
00068    *
00069    * \param max_noutput_items the maximum number of output items
00070    * allowed for any block in the flowgraph; the noutput_items can
00071    * always be less than this, but this will cap it as a maximum. Use
00072    * this to adjust the maximum latency a flowgraph can exhibit.
00073    */
00074   void start(int max_noutput_items=100000);
00075   
00076   /*!
00077    * Stop the running flowgraph.  Notifies each thread created by the
00078    * scheduler to shutdown, then returns to caller. Calling stop() on
00079    * a top_block that is already stopped IS NOT an error.
00080    */
00081   void stop();
00082 
00083   /*!
00084    * Wait for a flowgraph to complete.  Flowgraphs complete when
00085    * either (1) all blocks indicate that they are done (typically only
00086    * when using gr.file_source, or gr.head, or (2) after stop() has been
00087    * called to request shutdown.  Calling wait on a top_block that is
00088    * not running IS NOT an error (wait returns w/o blocking).
00089    */
00090   void wait();
00091 
00092   /*!
00093    * Lock a flowgraph in preparation for reconfiguration.  When an equal
00094    * number of calls to lock() and unlock() have occurred, the flowgraph
00095    * will be reconfigured.
00096    *
00097    * N.B. lock() and unlock() may not be called from a flowgraph thread
00098    * (E.g., gr_block::work method) or deadlock will occur when
00099    * reconfiguration happens.
00100    */
00101   virtual void lock();
00102 
00103   /*!
00104    * Unlock a flowgraph in preparation for reconfiguration.  When an equal
00105    * number of calls to lock() and unlock() have occurred, the flowgraph
00106    * will be reconfigured.
00107    *
00108    * N.B. lock() and unlock() may not be called from a flowgraph thread
00109    * (E.g., gr_block::work method) or deadlock will occur when
00110    * reconfiguration happens.
00111    */
00112   virtual void unlock();
00113 
00114   /*!
00115    * Displays flattened flowgraph edges and block connectivity
00116    */
00117   void dump();
00118 
00119   //! Get the number of max noutput_items in the flowgraph
00120   int max_noutput_items();
00121   
00122   //! Set the maximum number of noutput_items in the flowgraph
00123   void set_max_noutput_items(int nmax);
00124 
00125   gr_top_block_sptr to_top_block(); // Needed for Python/Guile type coercion
00126 };
00127 
00128 inline gr_top_block_sptr cast_to_top_block_sptr(gr_basic_block_sptr block) {
00129   return boost::dynamic_pointer_cast<gr_top_block, gr_basic_block>(block);
00130 }
00131 
00132 
00133 #endif /* INCLUDED_GR_TOP_BLOCK_H */