git.gag.com Git - debian/gnuradio/blob - mblock/src/lib/mb_mblock.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2006 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 2, 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 along
  18  * with this program; if not, write to the Free Software Foundation, Inc.,
  19  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21 #ifndef INCLUDED_MB_MBLOCK_H
  22 #define INCLUDED_MB_MBLOCK_H
  23
  24 #include <mb_common.h>
  25 #include <mb_message.h>
  26 #include <mb_port.h>
  27 #include <boost/enable_shared_from_this.hpp>
  28
  29
  30 /*!
  31  * Abstract class implementing visitor pattern
  32  * \ingroup internal
  33  */
  34 class mb_visitor
  35 {
  36 public:
  37   virtual ~mb_visitor();
  38   virtual bool operator()(mb_mblock *mblock, const std::string &path) = 0;
  39 };
  40
  41 // ----------------------------------------------------------------------
  42
  43 /*!
  44  * \brief Parent class for all message passing blocks
  45  *
  46  * Subclass this to define your mblocks.
  47  */
  48 class mb_mblock : boost::noncopyable,
  49                   public boost::enable_shared_from_this<mb_mblock>
  50 {
  51 private:
  52   mb_mblock_impl_sptr           d_impl;         // implementation details
  53
  54   friend class mb_runtime;
  55   friend class mb_mblock_impl;
  56
  57 protected:
  58   /*!
  59    * \brief mblock constructor.
  60    *
  61    * Initializing all mblocks in the system is a 3 step procedure.
  62    *
  63    * The top level mblock's constructor is run.  That constructor (a)
  64    * registers all of its ports using define_port, (b) constructs and
  65    * registers any subcomponents it may have via the define_component
  66    * method, and then (c) issues connect calls to wire its
  67    * subcomponents together.
  68    */
  69   mb_mblock();
  70
  71 public:
  72   /*!
  73    * \brief Called by the runtime system to execute the initial
  74    * transition of the finite state machine.
  75    *
  76    * Override this to initialize your finite state machine.
  77    */
  78   virtual void init_fsm();
  79
  80 protected:
  81   /*!
  82    * \brief Called by the runtime system when there's a message to handle.
  83    *
  84    * Override this to define your behavior.
  85    *
  86    * Do not issue any potentially blocking calls in this method.  This
  87    * includes things such reads or writes on sockets, pipes or slow
  88    * i/o devices.
  89    */
  90   virtual void handle_message(mb_message_sptr msg);
  91
  92   /*!
  93    * \brief Define a port.
  94    *
  95    * EXTERNAL and RELAY ports are part of our peer interface.
  96    * INTERNAL ports are used to talk to sub-components.
  97    *
  98    * \param port_name    The name of the port (must be unique within this mblock).
  99    * \param protocol_class_name The name of the protocol class associated with
 100    *                            this port.  It must already be defined.
 101    * \param conjugated   Are the incoming and outgoing message sets swapped?
 102    * \param port_type    INTERNAL, EXTERNAL or RELAY.
 103    */
 104   mb_port_sptr
 105   define_port(const std::string &port_name,
 106               const std::string &protocol_class_name,
 107               bool conjugated,
 108               mb_port::port_type_t port_type);
 109
 110   /*!
 111    * \brief Define a subcomponent by name.
 112    *
 113    * Called within the constructor to tell the system the
 114    * names and identities of our sub-component mblocks.
 115    *
 116    * \param component_name  The name of the sub-component (must be unique with this mblock).
 117    * \param component       The sub-component instance.
 118    */
 119   void
 120   define_component(const std::string &component_name,
 121                    mb_mblock_sptr component);
 122
 123   /*!
 124    * \brief connect endpoint_1 to endpoint_2
 125    *
 126    * \param comp_name1  component on one end of the connection
 127    * \param port_name1  the name of the port on comp1
 128    * \param comp_name2  component on the other end of the connection
 129    * \param port_name2  the name of the port on comp2
 130    *
 131    * An endpoint is specified by the component's local name (given as
 132    * component_name in the call to register_component) and the name of
 133    * the port on that component.
 134    *
 135    * To connect an internal or relay port, use "self" as the component name.
 136    */
 137   void
 138   connect(const std::string &comp_name1, const std::string &port_name1,
 139           const std::string &comp_name2, const std::string &port_name2);
 140
 141   /*!
 142    * \brief disconnect endpoint_1 from endpoint_2
 143    *
 144    * \param comp_name1  component on one end of the connection
 145    * \param port_name1  the name of the port on comp1
 146    * \param comp_name2  component on the other end of the connection
 147    * \param port_name2  the name of the port on comp2
 148    *
 149    * An endpoint is specified by the component's local name (given as
 150    * component_name in the call to register_component) and the name of
 151    * the port on that component.
 152    *
 153    * To disconnect an internal or relay port, use "self" as the component name.
 154    */
 155   void
 156   disconnect(const std::string &comp_name1, const std::string &port_name1,
 157              const std::string &comp_name2, const std::string &port_name2);
 158
 159   /*!
 160    * \brief disconnect all connections to specified component
 161    * \param component_name component to disconnect
 162    */
 163   void
 164   disconnect_component(const std::string component_name);
 165
 166   /*!
 167    * \brief disconnect all connections to all components
 168    */
 169   void
 170   disconnect_all();
 171
 172   /*!
 173    * \brief Return number of connections (QA mostly)
 174    */
 175   int
 176   nconnections() const;
 177
 178
 179 public:
 180   virtual ~mb_mblock();
 181
 182   void set_fullname(const std::string name);
 183
 184   //! Return full name of this block
 185   std::string fullname() const;
 186
 187   //! Return the parent of this mblock, or 0 if we're the top-level block.
 188   mb_mblock *parent() const;
 189
 190   /*!
 191    * \brief Perform a pre-order depth-first traversal of the hierarchy.
 192    *
 193    * The traversal stops and returns false if any call to visitor returns false.
 194    */
 195   bool
 196   walk_tree(mb_visitor *visitor, const std::string &path="top");
 197
 198
 199   //! \implementation
 200   // internal use only
 201   mb_mblock_impl_sptr
 202   impl() const { return d_impl; }
 203
 204 };
 205
 206
 207 #endif /* INCLUDED_MB_MBLOCK_H */