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

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2007 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  *
  35  */
  36 class gr_top_block : public gr_hier_block2
  37 {
  38 private:
  39   friend gr_top_block_sptr gr_make_top_block(const std::string &name);
  40
  41   gr_top_block_impl *d_impl;
  42
  43 protected:
  44   gr_top_block(const std::string &name);
  45
  46 public:
  47   ~gr_top_block();
  48
  49   /*!
  50    * \brief The simple interface to running a flowgraph.
  51    *
  52    * Calls start() then wait().  Used to run a flowgraph that will stop
  53    * on its own, or to run a flowgraph indefinitely until SIGINT is
  54    * received.
  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.
  62    */
  63   void start();
  64
  65   /*!
  66    * Stop the running flowgraph.  Notifies each thread created by the
  67    * scheduler to shutdown, then returns to caller.
  68    */
  69   void stop();
  70
  71   /*!
  72    * Wait for a flowgraph to complete.  Flowgraphs complete when
  73    * either (1) all blocks indicate that they are done (typically only
  74    * when using gr.file_source, or gr.head, or (2) after stop() has been
  75    * called to request shutdown.
  76    */
  77   void wait();
  78
  79   /*!
  80    * Lock a flowgraph in preparation for reconfiguration.  When an equal
  81    * number of calls to lock() and unlock() have occurred, the flowgraph
  82    * will be restarted automatically.
  83    *
  84    * N.B. lock() and unlock() cannot be called from a flowgraph thread
  85    * (E.g., gr_block::work method) or deadlock will occur when
  86    * reconfiguration happens.
  87    */
  88   virtual void lock();
  89
  90   /*!
  91    * Lock a flowgraph in preparation for reconfiguration.  When an equal
  92    * number of calls to lock() and unlock() have occurred, the flowgraph
  93    * will be restarted automatically.
  94    *
  95    * N.B. lock() and unlock() cannot be called from a flowgraph thread
  96    * (E.g., gr_block::work method) or deadlock will occur when
  97    * reconfiguration happens.
  98    */
  99   virtual void unlock();
 100
 101   /*!
 102    * Returns true if flowgraph is running
 103    */
 104   bool is_running();
 105 };
 106
 107 #endif /* INCLUDED_GR_TOP_BLOCK_H */