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