git.gag.com Git - debian/gnuradio/blob - gnuradio-core/src/lib/runtime/gr_top_block.h

   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_hier_block2.h>
  27
  28 class gr_top_block_impl;
  29
  30 gr_top_block_sptr gr_make_top_block(const std::string &name);
  31
  32 /*!
  33  *\brief Top-level hierarchical block representing a flowgraph
  34  * \ingroup container_blk
  35  *
  36  */
  37 class gr_top_block : public gr_hier_block2
  38 {
  39 private:
  40   friend gr_top_block_sptr gr_make_top_block(const std::string &name);
  41
  42   gr_top_block_impl *d_impl;
  43
  44 protected:
  45   gr_top_block(const std::string &name);
  46
  47 public:
  48   ~gr_top_block();
  49
  50   /*!
  51    * \brief The simple interface to running a flowgraph.
  52    *
  53    * Calls start() then wait().  Used to run a flowgraph that will stop
  54    * on its own, or when another thread will call stop().
  55    */
  56   void run();
  57
  58   /*!
  59    * Start the contained flowgraph.  Creates one or more threads to
  60    * execute the flow graph.  Returns to the caller once the threads
  61    * are created.  Calling start() on a top_block that is already
  62    * started IS an error.
  63    */
  64   void start();
  65
  66   /*!
  67    * Stop the running flowgraph.  Notifies each thread created by the
  68    * scheduler to shutdown, then returns to caller. Calling stop() on
  69    * a top_block that is already stopped IS NOT an error.
  70    */
  71   void stop();
  72
  73   /*!
  74    * Wait for a flowgraph to complete.  Flowgraphs complete when
  75    * either (1) all blocks indicate that they are done (typically only
  76    * when using gr.file_source, or gr.head, or (2) after stop() has been
  77    * called to request shutdown.  Calling wait on a top_block that is
  78    * not running IS NOT an error (wait returns w/o blocking).
  79    */
  80   void wait();
  81
  82   /*!
  83    * Lock a flowgraph in preparation for reconfiguration.  When an equal
  84    * number of calls to lock() and unlock() have occurred, the flowgraph
  85    * will be reconfigured.
  86    *
  87    * N.B. lock() and unlock() may not be called from a flowgraph thread
  88    * (E.g., gr_block::work method) or deadlock will occur when
  89    * reconfiguration happens.
  90    */
  91   virtual void lock();
  92
  93   /*!
  94    * Unlock a flowgraph in preparation for reconfiguration.  When an equal
  95    * number of calls to lock() and unlock() have occurred, the flowgraph
  96    * will be reconfigured.
  97    *
  98    * N.B. lock() and unlock() may not be called from a flowgraph thread
  99    * (E.g., gr_block::work method) or deadlock will occur when
 100    * reconfiguration happens.
 101    */
 102   virtual void unlock();
 103
 104   /*!
 105    * Displays flattened flowgraph edges and block connectivity
 106    */
 107   void dump();
 108 };
 109
 110 #endif /* INCLUDED_GR_TOP_BLOCK_H */