switch source package format to 3.0 quilt

[debian/gnuradio] / gnuradio-core / src / lib / runtime / gr_top_block.h

diff --git a/gnuradio-core/src/lib/runtime/gr_top_block.h b/gnuradio-core/src/lib/runtime/gr_top_block.h
index 16fd97074f1b13b1981b444c4458ce2495adc271..8052954e37902bc96232474930a9906a97e80d85 100644 (file)
--- a/gnuradio-core/src/lib/runtime/gr_top_block.h
+++ b/gnuradio-core/src/lib/runtime/gr_top_block.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2007 Free Software Foundation, Inc.
+ * Copyright 2007,2008,2009 Free Software Foundation, Inc.
  * 
  * This file is part of GNU Radio
  * 
@@ -31,6 +31,7 @@ gr_top_block_sptr gr_make_top_block(const std::string &name);
 
 /*!
  *\brief Top-level hierarchical block representing a flowgraph
+ * \ingroup container_blk
  *
  */
 class gr_top_block : public gr_hier_block2
@@ -47,49 +48,63 @@ public:
   ~gr_top_block();
 
   /*!
-   * Start the enclosed flowgraph.  Creates an undetached scheduler thread for
-   * each flow graph partition. Returns to caller once created.
+   * \brief The simple interface to running a flowgraph.
+   *
+   * Calls start() then wait().  Used to run a flowgraph that will stop
+   * on its own, or when another thread will call stop().
+   */
+  void run();
+
+  /*!
+   * Start the contained flowgraph.  Creates one or more threads to
+   * execute the flow graph.  Returns to the caller once the threads
+   * are created.  Calling start() on a top_block that is already
+   * started IS an error.
    */
   void start();
   
   /*!
-   * Stop the running flowgraph.  Tells each created scheduler thread
-   * to exit, then returns to caller.
+   * Stop the running flowgraph.  Notifies each thread created by the
+   * scheduler to shutdown, then returns to caller. Calling stop() on
+   * a top_block that is already stopped IS NOT an error.
    */
   void stop();
 
   /*!
-   * Wait for a stopped flowgraph to complete.  Joins each completed
-   * thread.
+   * Wait for a flowgraph to complete.  Flowgraphs complete when
+   * either (1) all blocks indicate that they are done (typically only
+   * when using gr.file_source, or gr.head, or (2) after stop() has been
+   * called to request shutdown.  Calling wait on a top_block that is
+   * not running IS NOT an error (wait returns w/o blocking).
    */
   void wait();
 
-  /*!
-   * Calls start(), then wait().  Used to run a flowgraph that will stop
-   * on its own, or to run a flowgraph indefinitely until SIGKILL is
-   * received().
-   */
-  void run();
-
   /*!
    * Lock a flowgraph in preparation for reconfiguration.  When an equal
    * number of calls to lock() and unlock() have occurred, the flowgraph
-   * will be restarted automatically.
+   * will be reconfigured.
    *
-   * N.B. lock() and unlock() cannot be called from a flowgraph thread or
-   * deadlock will occur when reconfiguration happens.
+   * N.B. lock() and unlock() may not be called from a flowgraph thread
+   * (E.g., gr_block::work method) or deadlock will occur when
+   * reconfiguration happens.
    */
   virtual void lock();
 
   /*!
-   * Lock a flowgraph in preparation for reconfiguration.  When an equal
+   * Unlock a flowgraph in preparation for reconfiguration.  When an equal
    * number of calls to lock() and unlock() have occurred, the flowgraph
-   * will be restarted automatically.
+   * will be reconfigured.
    *
-   * N.B. lock() and unlock() cannot be called from a flowgraph thread or
-   * deadlock will occur when reconfiguration happens.
+   * N.B. lock() and unlock() may not be called from a flowgraph thread
+   * (E.g., gr_block::work method) or deadlock will occur when
+   * reconfiguration happens.
    */
   virtual void unlock();
+
+  /*!
+   * Displays flattened flowgraph edges and block connectivity
+   */
+  void dump();
 };
 
 #endif /* INCLUDED_GR_TOP_BLOCK_H */