mb_mblock Class Reference

Parent class for all message passing blocks. More...

#include <mblock.h>

List of all members.

Public Member Functions

virtual void initial_transition ()
 Called by the runtime system to execute the initial transition of the finite state machine.
virtual ~mb_mblock ()
std::string instance_name () const
 Return instance name of this block.
std::string class_name () const
 Return the class name of this block.
void set_instance_name (const std::string &name)
 Set the instance name of this block.
mb_mblockparent () const
 Return the parent of this mblock, or 0 if we're the top-level block.
pmt_t schedule_one_shot_timeout (const mb_time &abs_time, pmt_t user_data)
 Schedule a "one shot" timeout.
pmt_t schedule_periodic_timeout (const mb_time &first_abs_time, const mb_time &delta_time, pmt_t user_data)
 Schedule a periodic timeout.
void cancel_timeout (pmt_t handle)
 Attempt to cancel a pending timeout.
bool walk_tree (mb_visitor *visitor)
 Perform a pre-order depth-first traversal of the hierarchy.
mb_mblock_impl_sptr impl () const

Protected Member Functions

 mb_mblock (mb_runtime *runtime, const std::string &instance_name, pmt_t user_arg)
 mblock constructor.
virtual void handle_message (mb_message_sptr msg)
 Called by the runtime system when there's a message to handle.
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)
 Define a port.
void define_component (const std::string &component_name, const std::string &class_name, pmt_t user_arg=PMT_NIL)
 Define a subcomponent by name.
void connect (const std::string &comp_name1, const std::string &port_name1, const std::string &comp_name2, const std::string &port_name2)
 connect endpoint_1 to endpoint_2
void disconnect (const std::string &comp_name1, const std::string &port_name1, const std::string &comp_name2, const std::string &port_name2)
 disconnect endpoint_1 from endpoint_2
void disconnect_component (const std::string &component_name)
 disconnect all connections to specified component
void disconnect_all ()
 disconnect all connections to all components
int nconnections () const
 Return number of connections (QA mostly).
void set_class_name (const std::string &name)
 Set the class name.
void exit ()
 Tell runtime that we are done.
void shutdown_all (pmt_t result)
 Ask runtime to execute the shutdown procedure for all blocks.
virtual void main_loop ()
 main event dispatching loop

Friends

class mb_runtime
class mb_mblock_impl
class mb_worker


Detailed Description

Parent class for all message passing blocks.

Subclass this to define your mblocks.


Constructor & Destructor Documentation

mb_mblock::mb_mblock ( mb_runtime runtime,
const std::string &  instance_name,
pmt_t  user_arg 
) [protected]

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.

Parameters:
runtime the runtime associated with this mblock
instance_name specify the name of this instance (for debugging, NUMA mapping, etc)
user_arg argument passed by user to constructor (ignored by the mb_mblock base class)

virtual mb_mblock::~mb_mblock (  )  [virtual]


Member Function Documentation

void mb_mblock::cancel_timeout ( pmt_t  handle  ) 

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.

Parameters:
handle returned from schedule_one_shot_timeout or schedule_periodic_timeout.

std::string mb_mblock::class_name (  )  const

Return the class name of this block.

void mb_mblock::connect ( const std::string &  comp_name1,
const std::string &  port_name1,
const std::string &  comp_name2,
const std::string &  port_name2 
) [protected]

connect endpoint_1 to endpoint_2

Parameters:
comp_name1 component on one end of the connection
port_name1 the name of the port on comp1
comp_name2 component on the other end of the connection
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 mb_mblock::define_component ( const std::string &  component_name,
const std::string &  class_name,
pmt_t  user_arg = PMT_NIL 
) [protected]

Define a subcomponent by name.

Called within the constructor to tell the system the names and identities of our sub-component mblocks.

Parameters:
component_name The name of the sub-component (must be unique with this mblock).
class_name The class of the instance that is to be created.
user_arg The argument to pass to the constructor of the component.

mb_port_sptr mb_mblock::define_port ( const std::string &  port_name,
const std::string &  protocol_class_name,
bool  conjugated,
mb_port::port_type_t  port_type 
) [protected]

Define a port.

EXTERNAL and RELAY ports are part of our peer interface. INTERNAL ports are used to talk to sub-components.

Parameters:
port_name The name of the port (must be unique within this mblock).
protocol_class_name The name of the protocol class associated with this port. It must already be defined.
conjugated Are the incoming and outgoing message sets swapped?
port_type INTERNAL, EXTERNAL or RELAY.

void mb_mblock::disconnect ( const std::string &  comp_name1,
const std::string &  port_name1,
const std::string &  comp_name2,
const std::string &  port_name2 
) [protected]

disconnect endpoint_1 from endpoint_2

Parameters:
comp_name1 component on one end of the connection
port_name1 the name of the port on comp1
comp_name2 component on the other end of the connection
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 mb_mblock::disconnect_all (  )  [protected]

disconnect all connections to all components

void mb_mblock::disconnect_component ( const std::string &  component_name  )  [protected]

disconnect all connections to specified component

Parameters:
component_name component to disconnect

void mb_mblock::exit (  )  [protected]

Tell runtime that we are done.

This method does not return.

virtual void mb_mblock::handle_message ( mb_message_sptr  msg  )  [protected, virtual]

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.

mb_mblock_impl_sptr mb_mblock::impl (  )  const [inline]

virtual void mb_mblock::initial_transition (  )  [virtual]

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.

std::string mb_mblock::instance_name (  )  const

Return instance name of this block.

virtual void mb_mblock::main_loop (  )  [protected, virtual]

main event dispatching loop

Although it is possible to override this, the default implementation should work for virtually all cases.

int mb_mblock::nconnections (  )  const [protected]

Return number of connections (QA mostly).

mb_mblock* mb_mblock::parent (  )  const

Return the parent of this mblock, or 0 if we're the top-level block.

pmt_t mb_mblock::schedule_one_shot_timeout ( const mb_time abs_time,
pmt_t  user_data 
)

Schedule a "one shot" timeout.

Parameters:
abs_time the absolute time at which the timeout should fire
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 mb_mblock::schedule_periodic_timeout ( const mb_time first_abs_time,
const mb_time delta_time,
pmt_t  user_data 
)

Schedule a periodic timeout.

Parameters:
first_abs_time The absolute time at which the first timeout should fire.
delta_time The relative delay between the first and successive timeouts.
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.

void mb_mblock::set_class_name ( const std::string &  name  )  [protected]

Set the class name.

void mb_mblock::set_instance_name ( const std::string &  name  ) 

Set the instance name of this block.

void mb_mblock::shutdown_all ( pmt_t  result  )  [protected]

Ask runtime to execute the shutdown procedure for all blocks.

Parameters:
result sets value of 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.

bool mb_mblock::walk_tree ( mb_visitor visitor  ) 

Perform a pre-order depth-first traversal of the hierarchy.

The traversal stops and returns false if any call to visitor returns false.


Friends And Related Function Documentation

friend class mb_mblock_impl [friend]

friend class mb_runtime [friend]

friend class mb_worker [friend]


The documentation for this class was generated from the following file:

Generated on Wed Jul 29 06:33:13 2009 for GNU Radio 3.2.2 C++ API by  doxygen 1.5.9