#include <Topology.hpp>

Inheritance diagram for Pothos::Topology:

Public Member Functions
	Topology (void)
	Create a new empty topology. More...

	~Topology (void)

void	setThreadPool (const ThreadPool &threadPool)
	Set the thread pool used by all blocks in this topology. More...

const ThreadPool &	getThreadPool (void) const
	Get the thread pool used by all blocks in this topology. More...

std::vector< PortInfo >	inputPortInfo (void)

std::vector< PortInfo >	outputPortInfo (void)

void	commit (void)

bool	waitInactive (const double idleDuration=0.1, const double timeout=1.0)

template<typename SrcType , typename SrcPortType , typename DstType , typename DstPortType >
void	connect (SrcType &&src, const SrcPortType &srcPort, DstType &&dst, const DstPortType &dstPort)

template<typename SrcType , typename SrcPortType , typename DstType , typename DstPortType >
void	disconnect (SrcType &&src, const SrcPortType &srcPort, DstType &&dst, const DstPortType &dstPort)

void	disconnectAll (const bool recursive=false)

void	_connect (const Object &src, const std::string &srcPort, const Object &dst, const std::string &dstPort)
	Create a connection between a source port and a destination port. More...

void	_disconnect (const Object &src, const std::string &srcPort, const Object &dst, const std::string &dstPort)
	Remove a connection between a source port and a destination port. More...

void	registerCallable (const std::string &name, const Callable &call)

std::string	queryJSONStats (void)

std::string	dumpJSON (const std::string &request="{}")

std::string	toDotMarkup (const std::string &request="{}")

Object	opaqueCallMethod (const std::string &name, const Object *inputArgs, const size_t numArgs) const

Public Member Functions inherited from Pothos::Connectable
virtual	~Connectable (void)
	virtual destructor for inheritance More...

void	setName (const std::string &name)

const std::string &	getName (void) const

std::vector< std::string >	inputPortNames (void)

std::vector< std::string >	outputPortNames (void)

Public Member Functions inherited from Pothos::CallInterface
virtual	~CallInterface (void)

template<typename ReturnType , typename... ArgsType>
ReturnType	call (ArgsType &&...args) const
	Call a bound method/function with a return type and variable args. More...

template<typename... ArgsType>
Object	callObject (ArgsType &&...args) const
	Call a bound method/function with an Object return and variable args. More...

template<typename... ArgsType>
void	callVoid (ArgsType &&...args) const
	Call a bound method/function with a void return and variable args. More...

Public Member Functions inherited from Pothos::Util::UID
	UID (void)
	Default constructor. More...

const std::string &	uid (void) const
	Get the UID as a string. More...

Public Member Functions inherited from Pothos::Util::RefHolder
virtual	~RefHolder (void)
	Virtual destructor for derived classes. More...

void	holdRef (const Object &container)
	Store a copy of this object container. More...

void	dropRef (const Object &container)
	Drop a copy of this object container. More...

Static Public Member Functions
static std::shared_ptr< Topology >	make (void)

static std::shared_ptr< Topology >	make (const std::string &json)

Public Attributes
std::shared_ptr< Impl >	_impl

Protected Member Functions
virtual Object	opaqueCallHandler (const std::string &name, const Object *inputArgs, const size_t numArgs)

Protected Member Functions inherited from Pothos::CallRegistry
virtual	~CallRegistry (void)
	Virtual destructor for subclassing. More...

template<typename... ArgsType, typename ReturnType , typename ClassType , typename InstanceType >
void	registerCall (InstanceType instance, const std::string &name, ReturnType(ClassType::method)(ArgsType...))

template<typename... ArgsType, typename ReturnType , typename ClassType , typename InstanceType >
void	registerCall (InstanceType instance, const std::string &name, ReturnType(ClassType::method)(ArgsType...) const)

virtual	~CallInterface (void)

template<typename ReturnType , typename... ArgsType>
ReturnType	call (ArgsType &&...args) const
	Call a bound method/function with a return type and variable args. More...

template<typename... ArgsType>
Object	callObject (ArgsType &&...args) const
	Call a bound method/function with an Object return and variable args. More...

template<typename... ArgsType>
void	callVoid (ArgsType &&...args) const
	Call a bound method/function with a void return and variable args. More...

Protected Member Functions inherited from Pothos::Util::UID
	UID (void)
	Default constructor. More...

const std::string &	uid (void) const
	Get the UID as a string. More...

Protected Member Functions inherited from Pothos::Util::RefHolder
virtual	~RefHolder (void)
	Virtual destructor for derived classes. More...

void	holdRef (const Object &container)
	Store a copy of this object container. More...

void	dropRef (const Object &container)
	Drop a copy of this object container. More...

Detailed Description

The Topology class maintains a list of data flows. The source of a flow is an output port on a Block or Topology. The destination of a flow is an input port on a Block or Topology. To create and destroy flows, make calls to connect and disconnect. To create hierarchy, a topology's connections can be made with itself; this action creates input and output ports for the topology.

Constructor & Destructor Documentation

Pothos::Topology::Topology ( void )

Create a new empty topology.

Pothos::Topology::~Topology ( void )

Cleanup and destroy a topology. This call simply disconnects all data flows and commits the changes.

Member Function Documentation

void Pothos::Topology::_connect	(	const Object &	src,
		const std::string &	srcPort,
		const Object &	dst,
		const std::string &	dstPort
	)

Create a connection between a source port and a destination port.

void Pothos::Topology::_disconnect	(	const Object &	src,
		const std::string &	srcPort,
		const Object &	dst,
		const std::string &	dstPort
	)

Remove a connection between a source port and a destination port.

void Pothos::Topology::commit ( void )

Commit changes made to the topology. Actual data flows created by connect and disconnect are not changed until a call to commit() is performed. Once commit is called, actual data flow processing begins. At this point the scheduler will call the block's work() functions when the data at its inputs becomes available.

template<typename SrcType , typename SrcPortType , typename DstType , typename DstPortType >

void Pothos::Topology::connect	(	SrcType &&	src,
		const SrcPortType &	srcPort,
		DstType &&	dst,
		const DstPortType &	dstPort
	)

Create a connection between a source port and a destination port.

Parameters

src	the data source (local/remote block/topology)
srcPort	an identifier for the source port (string or index)
dst	the data destination (local/remote block/topology)
dstPort	an identifier for the destination port (string or index)

template<typename SrcType , typename SrcPortType , typename DstType , typename DstPortType >

void Pothos::Topology::disconnect	(	SrcType &&	src,
		const SrcPortType &	srcPort,
		DstType &&	dst,
		const DstPortType &	dstPort
	)

Remove a connection between a source port and a destination port.

Parameters

src	the data source (local/remote block/topology)
srcPort	an identifier for the source port (string or index)
dst	the data destination (local/remote block/topology)
dstPort	an identifier for the destination port (string or index)

void Pothos::Topology::disconnectAll ( const bool recursive = false )

Disconnect all data flows inside this topology. This call can be recursive and will disconnect all on the other sub-topologies within this data flow. No changes to the data flow occur until commit().

Parameters

recursive true to recurse through sub-topologies

std::string Pothos::Topology::dumpJSON ( const std::string & request = "{}" )

Dump the topology state to a JSON formatted string. This call provides a structured view of the hierarchy.

Example request object {"mode" : "flat"}

Mode options:

"flat": Flattened hierarchies - only processing blocks.
"top": Only top-level blocks without hierarchy traversal.
"rendered": Flattened hierarchies with traversal blocks.

Example JSON markup for presenting the topology:

{
    "blocks" : {
        "uidblockA" : {
            "name" : "blockA",
            "outputs" : [
                {"name": "outx", "isSigSlot": false}
            ]
        },
        "uidblockB" : {
            "name" : "blockB",
            "inputs" : [
                {"name": "in0", "isSigSlot": false},
                {"name": "setFoo", "isSigSlot": true}
            ],
            "outputs" : [
                {"name": "out0", "isSigSlot": false},
                {"name": "barChanged", "isSigSlot": true}
            ]
        },
        "uidblockC" : {
            "name" : "blockC",
            "inputs" : [
                {"name": "iny", "isSigSlot": false}
            ],
            "blocks" : {#this is a hierarchy of blocks#},
            "connections" : {#this is a hierarchy of blocks#},
        }
    },
    "connections", [
        {"srcId": "uidblockA", "srcName": "outx", "dstId": "uidblockB", "srcName": "in0"},
        {"srcId": "uidblockB", "srcName": "out0", "dstId": "uidblockC", "srcName": "iny"}
    ]
}

Parameters

request a JSON object string with key/value arguments

Returns: a JSON formatted object string

const ThreadPool& Pothos::Topology::getThreadPool ( void ) const

Get the thread pool used by all blocks in this topology.

std::vector<PortInfo> Pothos::Topology::inputPortInfo ( void )

virtual

Get a vector of info about all of the input ports available.

Implements Pothos::Connectable.

static std::shared_ptr<Topology> Pothos::Topology::make ( void )

static

Create a new empty topology in a shared ptr. This is a convenience factory for Topology.

static std::shared_ptr<Topology> Pothos::Topology::make ( const std::string & json )

static

Create a topology from a JSON description.

JSON fields

The topology is a JSON object with fields to describe thread pools, global variables, blocks, and connections.

Thread pools

The "threadPools" field is an optional JSON object where each entry contains thread pool arguments which are documented by the ThreadPoolArgs JSON markup constructor. A block can be associated to a particular thread pool using the optional "threadPool" key and a pool name. The special thread pool with empty name "" will apply to all blocks that do not specify the "threadPool" key.

Global variables

The "globals" field is an optional JSON array where each entry is an object containing a variable name and value. The order of global variables matters here, because one global can reference another in an expression.

Blocks

The "blocks" field is an array of JSON objects, each of which describes a block by path, constructor args, and method calls.

The "id" of each block must be unique and will be referenced by the connections.
The "path" is the registered block factory path.
The "args" is a list of constructor arguments.
The "calls" is a list of ordered method calls. Each specified by the call name then arguments.
The "threadPool" specifies an optional thread pool by name

Connections

The "connections" field is an array of JSON arrays, where each array specifies a connection with source and destination ID and port name. The IDs are strings, but the port names can either be numbers or strings. Each connection entry has the following fields in order:

source ID
source port
destination ID
destination port

Using expressions

Global variable values and block arguments support expression parsing. The parser allows these values to be native JSON types: integers, floats, string, booleans, arrays, and objects. But they can also be strings containing expressions that make use of the global variables.

Because string can ambiguously represent actual strings and expressions. Every string is parsed as an expression and will fall-back to a regular unparsed string type if the parser fails to perform the evaluation. To literally pass a string argument that contains an expression that would be evaluated by the parser, simply use escaped quotes:

{"name" : "escapedExpr", "value" : "\"1+1\""}

Example markup

Example JSON markup for a topology description:

{
    "threadPools" : {
        "default" : {"priority" : 0.5},
        "myPool0" : {"yieldMode" : "SPIN"}
    },
    "globals" : [
         {"name" : "fiz", "value" : 3.14},
         {"name" : "baz", "value" : "-fiz"}
    ],
    "blocks" : [
        {
            "id" : "id0",
            "path" : "/blocks/foo",
            "args" : [1, "hello"],
            "calls" : [
                ["setFoo", true],
                ["updateBaz", "baz"]
            ]
        },
        {
            "id" : "id1",
            "path" : "/blocks/bar",
            "threadPool" : "myPool0",
            "args" : [],
            "calls" : [
                ["setBar", "OK"],
            ]
        }
    ],
    "connections", [
        ["self", "inputX", "id0", "in0"],
        ["id0", "out0", "id1", "in0"],
        ["id1", "out0", "self", "outputY"],
    ]
}

Parameters

json	a JSON formatted string

virtual Object Pothos::Topology::opaqueCallHandler	(	const std::string &	name,
		const Object *	inputArgs,
		const size_t	numArgs
	)

protectedvirtual

The opaque call handler handles dispatching calls to registered methods. The user may overload this call to install their own custom handler.

Exceptions

BlockCallNotFound	when no call registered for the provided name
Exception	when the registered call itself throws an exception

Parameters

name	the name of a call registered to this Block with registerCall()
inputArgs	an array of input arguments wrapped in type Object
numArgs	the number of arguments in the array inputArgs

Returns: the result of making the registered call, wrapped in type Object

Object Pothos::Topology::opaqueCallMethod	(	const std::string &	name,
		const Object *	inputArgs,
		const size_t	numArgs
	)		const

virtual

Call a method on a derived instance with opaque input and return types.

Parameters

name	the name of the method as a string
inputArgs	an array of input arguments
numArgs	the size of the input array

Returns: the return value as type Object

Implements Pothos::Connectable.

std::vector<PortInfo> Pothos::Topology::outputPortInfo ( void )

virtual

Get a vector of info about all of the output ports available.

Implements Pothos::Connectable.

std::string Pothos::Topology::queryJSONStats ( void )

Query performance statistics for all blocks in the topology.

Example JSON markup for stats reporting: (The actual stats markup has many more fields.)

{
    "unique_id_of_blockA" : {
        "blockName" : "blockA",
        "numWorkCalls" : 12345,
        "outputStats" : [
             {"portName" : "0", totalElements : 42},
        ]
    },
    "unique_id_of_blockB" : {
        "blockName" : "blockB",
        "numWorkCalls" : 6789,
        "inputStats" : [
             {"portName" : "0", totalElements : 0},
             {"portName" : "1", totalElements : 100}
        ]
    }
}

Returns: a JSON formatted object string

void Pothos::Topology::registerCallable	(	const std::string &	name,
		const Callable &	call
	)

virtual

Export a function call on this topology to set/get parameters. This call will automatically register a slot of the same name.

Parameters

name	the name of the callable
call	the bound callable method

Implements Pothos::CallRegistry.

void Pothos::Topology::setThreadPool ( const ThreadPool & threadPool )

Set the thread pool used by all blocks in this topology.

std::string Pothos::Topology::toDotMarkup ( const std::string & request = "{}" )

Convert the topology to a string containing dot markup. This markup can be passed into the dot tool to create a visual graph. The markup can represent the connections as specified by the user, or if flat is true, the complete flattened topology with network blocks for crossing process/computer boundaries.

Example request string {"mode" : "flat", "port" : "all"}

Mode options:

"flat": Flattened hierarchies - only processing blocks.
"top": Only top-level blocks without hierarchy traversal.
"rendered": Flattened hierarchies with traversal blocks.

Port options:

"all" Show all available IO ports.
"connected" Show connected ports only.

Parameters

request a JSON object string with configuration parameters

Returns: the dot markup as a string

bool Pothos::Topology::waitInactive	(	const double	idleDuration = `0.1`,
		const double	timeout = `1.0`
	)

Wait for a period of data flow inactivity. This call blocks until all flows become inactive for at least idleDuration seconds. This call is intended primarily for unit testing purposes to allow the topology to propagate test data through the entire flow from sources to sinks. Use a timeout value of 0.0 to wait forever for topology to become idle.

Parameters

idleDuration	the maximum number of seconds that flows may idle
timeout	the maximum number of seconds to wait in this call

Returns: true if the flow graph became inactive before the timeout

Member Data Documentation

std::shared_ptr<Impl> Pothos::Topology::_impl

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

include/Pothos/Framework/Topology.hpp
include/Pothos/Framework/TopologyImpl.hpp

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

JSON fields

Thread pools

Global variables

Blocks

Connections

Using expressions

Example markup

Member Data Documentation