ce0065f2db8184190275d5f030c33e0944764fe6
[debian/gnuradio] / 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   bool operator()(mb_mblock *mblock, const std::string &path) { return visit(mblock, path); }
38   virtual bool visit(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 {
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   /*!
71    * \brief Called by the runtime system to execute the initial
72    * transition of the finite state machine.
73    *
74    * Override this to initialize your finite state machine.
75    */
76   virtual void init_fsm();
77
78   /*!
79    * \brief Called by the runtime system when there's a message to handle.
80    *
81    * Override this to define your behavior.
82    *
83    * Do not issue any potentially blocking calls in this method.  This
84    * includes things such reads or writes on sockets, pipes or slow
85    * i/o devices.
86    */
87   virtual void handle_message(mb_message_sptr msg);
88
89   /*!
90    * \brief Define a port.
91    *
92    * EXTERNAL and RELAY ports are part of our peer interface.
93    * INTERNAL ports are used to talk to sub-components.
94    *
95    * \param port_name    The name of the port (must be unique within this mblock).
96    * \param protocol_class_name The name of the protocol class associated with
97    *                            this port.  It must already be defined.
98    * \param conjugated   Are the incoming and outgoing message sets swapped?
99    * \param port_type    INTERNAL, EXTERNAL or RELAY.
100    */
101   mb_port_sptr
102   define_port(const std::string &port_name,
103               const std::string &protocol_class_name,
104               bool conjugated,
105               mb_port::port_type_t port_type);
106
107   /*!
108    * \brief Define a subcomponent by name.
109    *
110    * Called within the constructor to tell the system the
111    * names and identities of our sub-component mblocks.
112    *
113    * \param component_name  The name of the sub-component (must be unique with this mblock).
114    * \param component       The sub-component instance.
115    */
116   void
117   define_component(const std::string &component_name,
118                    mb_mblock_sptr component);
119
120   /*!
121    * \brief connect endpoint_1 to endpoint_2
122    *
123    * \param comp_name1  component on one of the connection
124    * \param port_name1  the name of the port on comp1
125    * \param comp_name2  component on the other end the connection
126    * \param port_name2  the name of the port on comp2
127    *
128    * An endpoint is specified by the component's local name (given as
129    * component_name in the call to register_component) and the name of
130    * the port on that component.
131    *
132    * To connect an internal or relay port, use "self" as the component name.
133    */
134   void
135   connect(const std::string &comp_name1, const std::string &port_name1,
136           const std::string &comp_name2, const std::string &port_name2);
137
138   /*!
139    * \brief disconnect endpoint_1 from endpoint_2
140    *
141    * \param comp_name1  component on one of the connection
142    * \param port_name1  the name of the port on comp1
143    * \param comp_name2  component on the other end the connection
144    * \param port_name2  the name of the port on comp2
145    *
146    * An endpoint is specified by the component's local name (given as
147    * component_name in the call to register_component) and the name of
148    * the port on that component.
149    *
150    * To disconnect an internal or relay port, use "self" as the component name.
151    */
152   void
153   disconnect(const std::string &comp_name1, const std::string &port_name1,
154              const std::string &comp_name2, const std::string &port_name2);
155
156   /*!
157    * \brief disconnect all connections to specified component
158    * \param component_name component to disconnect
159    */
160   void
161   disconnect_component(const std::string component_name);
162
163   /*!
164    * \brief disconnect all connections to all components
165    */
166   void
167   disconnect_all();
168
169   /*!
170    * \brief Return number of connections (QA mostly)
171    */
172   int
173   nconnections() const;
174
175
176 public:
177   virtual ~mb_mblock();
178
179   /*!
180    * \brief Perform a pre-order depth-first traversal of the hierarchy.
181    *
182    * The traversal stops and returns false if any call to visitor returns false.
183    */
184   bool walk_tree(mb_visitor *visitor, const std::string &path="");
185 };
186
187
188 #endif /* INCLUDED_MB_MBLOCK_H */