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

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2007,2008 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 internal
  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 to run a flowgraph indefinitely until SIGINT is
  55    * received.
  56    */
  57   void run();
  58
  59   /*!
  60    * Start the contained flowgraph.  Creates one or more threads to
  61    * execute the flow graph.  Returns to the caller once the threads
  62    * are created.
  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.
  69    */
  70   void stop();
  71
  72   /*!
  73    * Wait for a flowgraph to complete.  Flowgraphs complete when
  74    * either (1) all blocks indicate that they are done (typically only
  75    * when using gr.file_source, or gr.head, or (2) after stop() has been
  76    * called to request shutdown.
  77    */
  78   void wait();
  79
  80   /*!
  81    * Lock a flowgraph in preparation for reconfiguration.  When an equal
  82    * number of calls to lock() and unlock() have occurred, the flowgraph
  83    * will be restarted automatically.
  84    *
  85    * N.B. lock() and unlock() cannot be called from a flowgraph thread
  86    * (E.g., gr_block::work method) or deadlock will occur when
  87    * reconfiguration happens.
  88    */
  89   virtual void lock();
  90
  91   /*!
  92    * Unlock a flowgraph in preparation for reconfiguration.  When an equal
  93    * number of calls to lock() and unlock() have occurred, the flowgraph
  94    * will be restarted automatically.
  95    *
  96    * N.B. lock() and unlock() cannot be called from a flowgraph thread
  97    * (E.g., gr_block::work method) or deadlock will occur when
  98    * reconfiguration happens.
  99    */
 100   virtual void unlock();
 101
 102   /*!
 103    * Displays flattened flowgraph edges and block connectivity
 104    */
 105   void dump();
 106 };
 107
 108 #endif /* INCLUDED_GR_TOP_BLOCK_H */