View source for GR4 tutorial: flowgraphs 101

This tutorial explains the basics of C++ flowgraphs in GNU Radio 4.0.

== Minimal flowgraph ==

The following is an example of a minimal flowgraph. It connects a Null Source to a Null Sink and runs the flowgraph forever. The code for the flowgraph can be found in [https://github.com/daniestevez/gr4-packet-modem/blob/main/examples/minimal_flowgraph.cpp minimal_flowgraph.cpp].

<syntaxhighlight lang="cpp" line>
#include <fmt/core.h>
#include <gnuradio-4.0/Graph.hpp>
#include <gnuradio-4.0/Scheduler.hpp>
#include <gnuradio-4.0/packet-modem/null_sink.hpp>
#include <gnuradio-4.0/packet-modem/null_source.hpp>
#include <boost/ut.hpp>

int main()
{
    using namespace boost::ut;

    gr::Graph fg;
    auto& source = fg.emplaceBlock<gr::packet_modem::NullSource<int>>();
    auto& sink = fg.emplaceBlock<gr::packet_modem::NullSink<int>>();
    expect(eq(gr::ConnectionResult::SUCCESS, fg.connect<"out">(source).to<"in">(sink)));

    gr::scheduler::Simple sched{ std::move(fg) };
    expect(sched.runAndWait().has_value());

    return 0;
}
</syntaxhighlight>

Here the [https://github.com/boost-ext/ut boost-ut] <code>expect()</code> function is used for error handling, since it is also used for unit testing in GNU Radio 4.0, but any other form of error handling can be used.

Creating a flowgraph in GNU Radio 4.0 begins with the instantiation of a <code>gr::Graph</code> object.

The <code>emplaceBlock()</code> method of the <code>gr::Graph</code> is used to add blocks to the flowgraph. Note that this method takes a template parameter which specifies the block class. The block classes can be templates, and they often have template parameters to indicate the input and output types. Here we are creating a <code>NullSource<int></code>, which has <code>int</code> as output type, and similarly for the null sink. As in GNU Radio 3.10, blocks can get parameters when they are created. These are passed as a <code>gr::property_map</code> argument to <code>emplaceBlock()</code>. In this case, the Null Source and Null Sink don't take any parameters, so <code>emplaceBlock()</code> is called without arguments. We will see an example of blocks with parameters below.

A connection between blocks is done by calling the <code>connect()</code> method of the <code>gr::Graph</code>. Note how the syntax works, using template parameters to specify the name of the ports. In GNU Radio 3.10, block ports have numbers 0, 1, 2, etc. These numbers are specified when calling <code>connect</code>, and 0 is implicit if the number is omitted. In GNU Radio 4.0, all the ports have names which are a string. In simple blocks which only have an input or an output, <code>"in"</code> and <code>"out"</code> are often used as port names. The <code>connect()</code> method checks that the connection is valid (the types of the ports match, etc.) and returns a <code>gr::ConnectionResult</code> value indicating if the connection could be made.

Once all the blocks have been added to the flowgraph and connected, the flowgraph can be run. To do this, it is first necessary to put the flowgraph in a scheduler. GNU Radio 3.10 has a single scheduler implemented in the runtime. In GNU Radio 4.0, schedulers are modular and users can implement their own, so any scheduler could be used here. In this example we use the <code>gr::Scheduler::Simple</code> scheduler, which is included in the GNU Radio 4.0 core. By default it is a single-threaded scheduler, meaning that it runs all of the blocks in the same thread (except for dedicated IO threads). It can also be instantiated as a multi-threaded scheduler that uses a one-thread-per-block approach similar to GNU Radio 3.10.

After the scheduler is created, its <code>runAndWait()</code> method is called. This is equivalent to the GNU Radio 3.10 <code>run()</code> method. It runs the flowgraph until the flowgraph finishes on its own (because the end of an input file has been reached, the limit on a [[Head]] block has been hit, etc.) The <code>runAndWait()</code> method also returns if there is an error, such as a block raising an unhandled exception. The method returns a [https://en.cppreference.com/w/cpp/utility/expected std::expected], so the <code>has_value()</code> method can be used to check if there was an error. This particular example flowgraph actually runs forever, and <code>runAndWait()</code> never returns, because the Null Source always keeps generating data.

== Block parameters ==

To show how block parameters can be passed when calling <code>emplaceBlock()</code>, we will add a Head block between the Null Source and the Null Sink in the flowgraph above. The relevant lines of code are the following. The complete example is in [https://github.com/daniestevez/gr4-packet-modem/blob/main/examples/head.cpp head.cpp].

<syntaxhighlight lang="cpp" line>
    auto& source = fg.emplaceBlock<gr::packet_modem::NullSource<int>>();
    auto& head =
        fg.emplaceBlock<gr::packet_modem::Head<int>>({ { "num_items", 1000UL } });
    auto& sink = fg.emplaceBlock<gr::packet_modem::NullSink<int>>();
    expect(eq(gr::ConnectionResult::SUCCESS, fg.connect<"out">(source).to<"in">(head)));
    expect(eq(gr::ConnectionResult::SUCCESS, fg.connect<"out">(head).to<"in">(sink)));
</syntaxhighlight>

The argument of the <code>emplaceBlock()</code> method is a <code>gr::property_map</code>, which is defined as <code>std::map<std::string, pmtv::pmt></code>. The [https://github.com/gnuradio/pmt pmtv] library is a replacement for the [[Polymorphic Types (PMTs)]] in GNU Radio 3.10 using modern C++ features. All the simple C++ types that you would expect can be converted to and from a <code>pmtv::pmt</code>. When calling <code>emplaceBlock()</code>, it is often convenient to create the <code>gr::property_map</code> by using C++ initializer lists, as is done in this example. Here the initializer list is <code>{ { "num_items", 1000UL } }</code>. Several parameters of different types can also be passed quite naturally, such as for example:

<syntaxhighlight lang="cpp">
{ { "foo", "var" }, { "amplitude", 37.1f }, { "samples", std::vector<double>{ 1.3, 2.5, -4.7 } } }
</syntaxhighlight>

'''Warning:''' This is the only way of passing parameters to a block on construction. Unlike in GNU Radio 3.10, it is not possible to have a C++ constructor that takes a list of arguments of arbitrary C++ types.

A natural question is how to find the parameters that a block has. We can check the C++ source for the block (here [https://github.com/daniestevez/gr4-packet-modem/blob/main/blocks/include/gnuradio-4.0/packet-modem/head.hpp head.hpp]). The parameters that can be set with a <code>gr::property_map</code> are declared in the reflection macro, which in this case is:

<syntaxhighlight lang="cpp">
ENABLE_REFLECTION_FOR_TEMPLATE(gr::packet_modem::Head, in, out, num_items);
</syntaxhighlight>

Note that the reflection macro also declares all the ports of the block. The parameters must be public class members. We can look at the class declaration to find their types. In this case we have the following:

<syntaxhighlight lang="cpp">
    gr::PortIn<T> in;
    gr::PortOut<T> out;
    uint64_t num_items;
</syntaxhighlight>

'''Warning:''' types are important when constructing the <code>gr::property_map</code> used to pass parameters to the block. In this case, using <code>{ { "num_items", 1000 } }</code> would cause a runtime error, because <code>1000</code> is an <code>int</code>, but the block expects <code>num_items</code> to be a <code>uint64_t</code>. Beware of numeric literals in C++. Often the type needs to be specified explicitly for these.

Another thing to note from this example is that connections are always done between two blocks. Unlike in GNU Radio 3.10, there is no shorthand notation to string connections through a list of multiple blocks.

When this flowgraph is run, we can see that it terminates almost immediately, unlike the previous example.

== Stopping a flowgraph ==

Unlike in GNU Radio 3.10, there is no <code>start()</code> method to start running a flowgraph and then do something else while the flowgraph runs. There is only <code>startAndWait()</code>, which only returns when the flowgraph is done. If we want to force the flowgraph to terminate early, the way to do it is to run a thread that sends a <code>REQUEST_STOP</code> message to the scheduler.

The following example shows how this can be done. The complete code for the example is in [https://github.com/daniestevez/gr4-packet-modem/blob/main/examples/stop_flowgraph.cpp stop_flowgraph.cpp]. In this case the thread sends the <code>REQUEST_STOP</code> message after 100 milliseconds, but any other kind of condition could be used to determine when to stop the flowgraph.

<syntaxhighlight lang="cpp" line>
    gr::scheduler::Simple sched{ std::move(fg) };

    gr::MsgPortOut toScheduler;
    expect(eq(gr::ConnectionResult::SUCCESS, toScheduler.connect(sched.msgIn)));

    // Spin a thread that sleeps 100 ms and sends a REQUEST_STOP message to the
    // scheduler. Without this message, the scheduler would run forever with
    // this flowgraph.
    std::thread stopper([&toScheduler]() {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
        gr::sendMessage<gr::message::Command::Set>(toScheduler,
                                                   "",
                                                   gr::block::property::kLifeCycleState,
                                                   { { "state", "REQUESTED_STOP" } });
    });

    expect(sched.runAndWait().has_value());

    stopper.join();
</syntaxhighlight>

After the flowgraph has stopped, the state of the blocks can be examined. The complete example includes a [[Vector Sink]] instead of a Null Sink, and it counts the number of items collected by the Vector Sink after the <code>stopper.join()</code> call returns.

== Connections to blocks with vectors of ports ==

In GNU Radio 4.0, blocks can have a port declared as a vector of ports. This is used to specify an arbitrary number of ports of the same type whose number is determined at runtime. For example a Packet Mux block that multiplexes packets from several inputs into one output might have its ports declared like this (see [https://github.com/daniestevez/gr4-packet-modem/blob/main/blocks/include/gnuradio-4.0/packet-modem/packet_mux.hpp packet_mux.hpp]).

<syntaxhighlight lang="cpp">
    std::vector<gr::PortIn<T>> in;
    gr::PortOut<T> out;
    size_t num_inputs = 0;
</syntaxhighlight>

The <code>num_inputs</code> parameter is passed when the block is added to the flowgraph to specify the desired number of inputs. Other types of blocks that might do the same are arithmetic blocks, such as Add and Multiply. The names of the ports are generated as the base port name ("in" in this case), followed by '#' and a number, so in this case the input ports would be <code>"in#0"</code>, <code>"in#1"</code>, etc.

The syntax introduced above to connect ports cannot be used with these vectors of ports, because the number of ports that actually exist in the block is only known at runtime, and this method of doing port connections checks that the port names exist at compile time. There is an alternate syntax to do connections that performs the check at runtime. This is the one that needs to be used in this case. It is done like so:

<syntaxhighlight lang="cpp">
using namespace std::string_literals;
fg.connect(block_0, "out"s, mux_block, "in#0"s);
fg.connect(block_1, "out"s, mux_block, "in#1"s);
// etc
</syntaxhighlight>

(Rember that <code>connect()</code> returns a <code>gr::ConnectionResult</code> that should be checked for errors). The port names are specified as <code>std::string</code> arguments, so using string literals is handy.

'''Tip:''' This alternate connection syntax can also be used to do port connections whose names are evaluated at runtime, regardless of whether they belong to a vector of ports.

== Message port connections ==

In GNU Radio 4.0, message ports are connected in the same way as regular ports. There is no specific <code>msg_connect()</code> to connect message ports. Any of the two methods shown above to do connections works with message ports too.