= Message Blocks =

Message blocks (or ''m-blocks'') are a GNU Radio extension, designed in cooperation with BBN, that allows more natural handling of packet-based data. Full details of the message block can be found in the original BBN proposal: http://acert.ir.bbn.com/downloads/adroit/gnuradio-architectural-enhancements-3.pdf

The ''message-block'' introduces several new capabilities to GNU Radio: * Processing of arbitrarily sized data blocks with metadata * Maintenance of time synchronization across a ''flow_graph'', threads, or processes * Generation of signals, handling of commands, and status reporting to and from external entities * Hierarchical quasi-real-time scheduling

A ''message-block'' is a bi-directional block in which information flows as messages that may contain data, metadata, control information, status information, and signals. Since ''m-blocks'' can communicate many different types of messages, each port is typed with a protocol class to ensure that only compatible ports are connected. This ensures that an ''m-block'' communicating control information is not connected with an ''m-block'' communicating status information. An ''m-block'' may have zero or more bi-directional message ports of the same protocol.

Multiple levels of aggregation can be used with the ''m-block'' such that ''m-blocks'' may be enclosed within each other. However, the ''m-block'' is not limited to containing other ''m-blocks''. It may contain collections of GNU Radio blocks or ''flow_graphs''. Aggregation allows for conversions between messages and streams of data samples to take place in an internal fashion to a single ''m-block''. The following terminology is used: * ''Simple m-block'': an ''m-block'' which does not contain any other ''m-blocks'' * ''Component m-block'': an ''m-block'' contained within another ''m-block'' * ''Aggregate m-block'': an ''m-block'' that contains other ''m-blocks''

Unlike GNU Radio blocks which are connected through a ''flow_graph'' which provides a scheduler and maintains topological information, the aggregation property of ''m-blocks'' require them to maintain their own topological information. There will only be a single top-level ''m-block'' that provides equivalent topological functionality of a GNU Radio ''flow_graph'', rather than a corresponding ''flow_graph'' being needed for each ''m-block''.

Each ''m-block'' has a processing callback function, `handle_message`, which handles the data and metadata processing as well as the message timing functionality. The `handle_message` callback relies on the scheduler for external event notification and therefore never blocks.

When used in conjunction with a priority based scheduler, the priority of the ''m-block'' will be the priority of the highest priority message within its queue. With a series of ''m-blocks'' in the scheduler, this allows for high priority signals to be processed quickly.

The messages that flow through ''m-blocks'' have two types of information: `metadata` and `data`. The metadata may contain the message version, timestamps, a priority, segmentation information, and commands/notifications from external entities. The data portion of the message carriers the data which may be transformed by blocks as it is passed through a ''flow_graph''.