Pothos  0.4.1-gb758ed46
The Pothos dataflow programming software suite
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | List of all members
Pothos::Topology Class Reference

#include <Topology.hpp>

Inheritance diagram for Pothos::Topology:
Inheritance graph
[legend]

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 ThreadPoolgetThreadPool (void) const
 Get the thread pool used by all blocks in this topology. More...
 
std::vector< PortInfoinputPortInfo (void)
 
std::vector< PortInfooutputPortInfo (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< Topologymake (void)
 
static std::shared_ptr< Topologymake (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
srcthe data source (local/remote block/topology)
srcPortan identifier for the source port (string or index)
dstthe data destination (local/remote block/topology)
dstPortan 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
srcthe data source (local/remote block/topology)
srcPortan identifier for the source port (string or index)
dstthe data destination (local/remote block/topology)
dstPortan 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
recursivetrue 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:

1 {
2  "blocks" : {
3  "uidblockA" : {
4  "name" : "blockA",
5  "outputs" : [
6  {"name": "outx", "isSigSlot": false}
7  ]
8  },
9  "uidblockB" : {
10  "name" : "blockB",
11  "inputs" : [
12  {"name": "in0", "isSigSlot": false},
13  {"name": "setFoo", "isSigSlot": true}
14  ],
15  "outputs" : [
16  {"name": "out0", "isSigSlot": false},
17  {"name": "barChanged", "isSigSlot": true}
18  ]
19  },
20  "uidblockC" : {
21  "name" : "blockC",
22  "inputs" : [
23  {"name": "iny", "isSigSlot": false}
24  ],
25  "blocks" : {#this is a hierarchy of blocks#},
26  "connections" : {#this is a hierarchy of blocks#},
27  }
28  },
29  "connections", [
30  {"srcId": "uidblockA", "srcName": "outx", "dstId": "uidblockB", "srcName": "in0"},
31  {"srcId": "uidblockB", "srcName": "out0", "dstId": "uidblockC", "srcName": "iny"}
32  ]
33 }
Parameters
requesta 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:

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

Example markup

Example JSON markup for a topology description:

1 {
2  "threadPools" : {
3  "default" : {"priority" : 0.5},
4  "myPool0" : {"yieldMode" : "SPIN"}
5  },
6  "globals" : [
7  {"name" : "fiz", "value" : 3.14},
8  {"name" : "baz", "value" : "-fiz"}
9  ],
10  "blocks" : [
11  {
12  "id" : "id0",
13  "path" : "/blocks/foo",
14  "args" : [1, "hello"],
15  "calls" : [
16  ["setFoo", true],
17  ["updateBaz", "baz"]
18  ]
19  },
20  {
21  "id" : "id1",
22  "path" : "/blocks/bar",
23  "threadPool" : "myPool0",
24  "args" : [],
25  "calls" : [
26  ["setBar", "OK"],
27  ]
28  }
29  ],
30  "connections", [
31  ["self", "inputX", "id0", "in0"],
32  ["id0", "out0", "id1", "in0"],
33  ["id1", "out0", "self", "outputY"],
34  ]
35 }
Parameters
jsona 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
BlockCallNotFoundwhen no call registered for the provided name
Exceptionwhen the registered call itself throws an exception
Parameters
namethe name of a call registered to this Block with registerCall()
inputArgsan array of input arguments wrapped in type Object
numArgsthe 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
namethe name of the method as a string
inputArgsan array of input arguments
numArgsthe 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.)

1 {
2  "unique_id_of_blockA" : {
3  "blockName" : "blockA",
4  "numWorkCalls" : 12345,
5  "outputStats" : [
6  {"portName" : "0", totalElements : 42},
7  ]
8  },
9  "unique_id_of_blockB" : {
10  "blockName" : "blockB",
11  "numWorkCalls" : 6789,
12  "inputStats" : [
13  {"portName" : "0", totalElements : 0},
14  {"portName" : "1", totalElements : 100}
15  ]
16  }
17 }
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
namethe name of the callable
callthe 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
requesta 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
idleDurationthe maximum number of seconds that flows may idle
timeoutthe 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: