/* -*- c++ -*- */
/*
* Copyright 2006 Free Software Foundation, Inc.
*
* This file is part of GNU Radio
*
* GNU Radio is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 3, or (at your option)
* any later version.
*
* GNU Radio is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
#ifndef INCLUDED_MB_MBLOCK_H
#define INCLUDED_MB_MBLOCK_H
#include <mb_common.h>
#include <mb_message.h>
#include <mb_port.h>
#include <mb_time.h>
/*!
* Abstract class implementing visitor pattern
* \ingroup internal
*/
class mb_visitor
{
public:
virtual ~mb_visitor();
virtual bool operator()(mb_mblock *mblock) = 0;
};
// ----------------------------------------------------------------------
/*!
* \brief Parent class for all message passing blocks
*
* Subclass this to define your mblocks.
*/
class mb_mblock : boost::noncopyable,
public boost::enable_shared_from_this<mb_mblock>
{
private:
mb_mblock_impl_sptr d_impl; // implementation details
friend class mb_runtime;
friend class mb_mblock_impl;
friend class mb_worker;
protected:
/*!
* \brief mblock constructor.
*
* Initializing all mblocks in the system is a 3 step procedure.
*
* The top level mblock's constructor is run. That constructor
* (a) registers all of its ports using define_port, (b) registers any
* subcomponents it may have via the define_component method, and
* then (c) issues connect calls to wire its subcomponents together.
*
* \param runtime the runtime associated with this mblock
* \param instance_name specify the name of this instance
* (for debugging, NUMA mapping, etc)
* \param user_arg argument passed by user to constructor
* (ignored by the mb_mblock base class)
*/
mb_mblock(mb_runtime *runtime, const std::string &instance_name, pmt_t user_arg);
public:
/*!
* \brief Called by the runtime system to execute the initial
* transition of the finite state machine.
*
* This method is called by the runtime after all blocks are
* constructed and before the first message is delivered. Override
* this to initialize your finite state machine.
*/
virtual void initial_transition();
protected:
/*!
* \brief Called by the runtime system when there's a message to handle.
*
* Override this to define your behavior.
*
* Do not issue any potentially blocking calls in this method. This
* includes things such reads or writes on sockets, pipes or slow
* i/o devices.
*/
virtual void handle_message(mb_message_sptr msg);
/*!
* \brief Define a port.
*
* EXTERNAL and RELAY ports are part of our peer interface.
* INTERNAL ports are used to talk to sub-components.
*
* \param port_name The name of the port (must be unique within this mblock).
* \param protocol_class_name The name of the protocol class associated with
* this port. It must already be defined.
* \param conjugated Are the incoming and outgoing message sets swapped?
* \param port_type INTERNAL, EXTERNAL or RELAY.
*/
mb_port_sptr
define_port(const std::string &port_name,
const std::string &protocol_class_name,
bool conjugated,
mb_port::port_type_t port_type);
/*!
* \brief Define a subcomponent by name.
*
* Called within the constructor to tell the system the
* names and identities of our sub-component mblocks.
*
* \param component_name The name of the sub-component (must be unique with this mblock).
* \param class_name The class of the instance that is to be created.
* \param user_arg The argument to pass to the constructor of the component.
*/
void
define_component(const std::string &component_name,
const std::string &class_name,
pmt_t user_arg = PMT_NIL);
/*!
* \brief connect endpoint_1 to endpoint_2
*
* \param comp_name1 component on one end of the connection
* \param port_name1 the name of the port on comp1
* \param comp_name2 component on the other end of the connection
* \param port_name2 the name of the port on comp2
*
* An endpoint is specified by the component's local name (given as
* component_name in the call to register_component) and the name of
* the port on that component.
*
* To connect an internal or relay port, use "self" as the component name.
*/
void
connect(const std::string &comp_name1, const std::string &port_name1,
const std::string &comp_name2, const std::string &port_name2);
/*!
* \brief disconnect endpoint_1 from endpoint_2
*
* \param comp_name1 component on one end of the connection
* \param port_name1 the name of the port on comp1
* \param comp_name2 component on the other end of the connection
* \param port_name2 the name of the port on comp2
*
* An endpoint is specified by the component's local name (given as
* component_name in the call to register_component) and the name of
* the port on that component.
*
* To disconnect an internal or relay port, use "self" as the component name.
*/
void
disconnect(const std::string &comp_name1, const std::string &port_name1,
const std::string &comp_name2, const std::string &port_name2);
/*!
* \brief disconnect all connections to specified component
* \param component_name component to disconnect
*/
void
disconnect_component(const std::string &component_name);
/*!
* \brief disconnect all connections to all components
*/
void
disconnect_all();
/*!
* \brief Return number of connections (QA mostly)
*/
int
nconnections() const;
//! Set the class name
void set_class_name(const std::string &name);
/*!
* \brief Tell runtime that we are done.
*
* This method does not return.
*/
void exit();
/*!
* \brief Ask runtime to execute the shutdown procedure for all blocks.
*
* \param result sets value of \p result output argument of runtime->run(...)
*
* The runtime first sends a maximum priority %shutdown message to
* all blocks. All blocks should handle the %shutdown message,
* perform whatever clean up is required, and call this->exit();
*
* After a period of time (~100ms), any blocks which haven't yet
* called this->exit() are sent a maximum priority %halt message.
* %halt is detected in main_loop, and this->exit() is called.
*
* After an additional period of time (~100ms), any blocks which
* still haven't yet called this->exit() are sent a SIG<FOO> (TBD)
* signal, which will blow them out of any blocking system calls and
* raise an mbe_terminate exception. The default top-level
* runtime-provided exception handler will call this->exit() to
* finish the process.
*
* runtime->run(...) returns when all blocks have called exit.
*/
void shutdown_all(pmt_t result);
/*!
* \brief main event dispatching loop
*
* Although it is possible to override this, the default implementation
* should work for virtually all cases.
*/
virtual void main_loop();
public:
virtual ~mb_mblock();
//! Return instance name of this block
std::string instance_name() const;
//! Return the class name of this block
std::string class_name() const;
//! Set the instance name of this block.
void set_instance_name(const std::string &name);
//! Return the parent of this mblock, or 0 if we're the top-level block.
mb_mblock *parent() const;
/*!
* \brief Schedule a "one shot" timeout.
*
* \param abs_time the absolute time at which the timeout should fire
* \param user_data the data passed in the %timeout message.
*
* When the timeout fires, a message will be sent to the mblock.
*
* The message will have port_id = %sys-port, signal = %timeout,
* data = user_data, metadata = the handle returned from
* schedule_one_shot_timeout, pri = MB_PRI_BEST.
*
* \returns a handle that can be used in cancel_timeout, and is passed
* as the metadata field of the generated %timeout message.
*
* To cancel a pending timeout, call cancel_timeout.
*/
pmt_t
schedule_one_shot_timeout(const mb_time &abs_time, pmt_t user_data);
/*!
* \brief Schedule a periodic timeout.
*
* \param first_abs_time The absolute time at which the first timeout should fire.
* \param delta_time The relative delay between the first and successive timeouts.
* \param user_data the data passed in the %timeout message.
*
* When the timeout fires, a message will be sent to the mblock, and a
* new timeout will be scheduled for previous absolute time + delta_time.
*
* The message will have port_id = %sys-port, signal = %timeout,
* data = user_data, metadata = the handle returned from
* schedule_one_shot_timeout, pri = MB_PRI_BEST.
*
* \returns a handle that can be used in cancel_timeout, and is passed
* as the metadata field of the generated %timeout message.
*
* To cancel a pending timeout, call cancel_timeout.
*/
pmt_t
schedule_periodic_timeout(const mb_time &first_abs_time,
const mb_time &delta_time,
pmt_t user_data);
/*!
* \brief Attempt to cancel a pending timeout.
*
* Note that this only stops a future timeout from firing. It is
* possible that a timeout may have already fired and enqueued a
* %timeout message, but that that message has not yet been seen by
* handle_message.
*
* \param handle returned from schedule_one_shot_timeout or schedule_periodic_timeout.
*/
void cancel_timeout(pmt_t handle);
/*!
* \brief Perform a pre-order depth-first traversal of the hierarchy.
*
* The traversal stops and returns false if any call to visitor returns false.
*/
bool
walk_tree(mb_visitor *visitor);
//! \implementation
// internal use only
mb_mblock_impl_sptr
impl() const { return d_impl; }
};
#endif /* INCLUDED_MB_MBLOCK_H */