Abstract class that implements a generic algorithm. More...

#include <QAlgorithm.h>

Inheritance diagram for QAlgorithm:

Public Slots
Q_SLOT void	parallelExecution ()
	Start computing the algorithm tree on different threads. More...

Q_SLOT void	serialExecution ()
	Start computing the algorithm tree on the calling thread. More...

Q_SLOT void	abort (QString message="Unknown Error") const
	Emit the given error signal. More...

Q_SLOT void	propagateExecution ()
	Execute descendants. More...

Signals
Q_SIGNAL void	justFinished ()
	Signal emitted on algorithm's end. More...

Q_SIGNAL void	justStarted ()
	Signal emitted on algorithm's start. More...

Q_SIGNAL void	raise (QString message) const
	Signal emitted whenever an error occurs. More...

Public Member Functions
void	setFinished ()
	Set the algorithm as comleted and signals it. More...

void	setStarted ()
	Set the algorithm as started and signals it. More...

	QAlgorithm (QObject *parent=Q_NULLPTR)
	Constructor. More...

virtual void	run ()=0
	Core part of the algorithm, to be reimplemented in subclasses. More...

QACompletionMap	getAncestors () const
	Get the value of ancestors. More...

QACompletionMap	getDescendants () const
	Get the value of descendants. More...

bool	allInputsReady () const
	Checks if the algorithm is ready to run. More...

bool	isStarted () const
	Get the value of started. More...

bool	isFinished () const
	Get the value of finished. More...

virtual bool	getInput (QAShrAlgorithm parent)
	Load inputs from parent's outputs. More...

virtual void	setParameters (const QAPropertyMap &parameters)
	Set parameters for the algorithm. More...

void	printGraph (const QString &path=QString()) const
	Create a GraphViz diagram of the algorithm tree. More...

QString	printName () const
	Returns name, memory address and class name of the algorithm. More...

QAFlatRepresentation	flattenTree (QAFlatRepresentation tree=QAFlatRepresentation()) const
	Creates a flat representation of the algorithm tree. More...

void	printTree (const QAFlatRepresentation &tree=QAFlatRepresentation()) const
	Outputs a text representation of the algorithm tree. More...

Static Public Member Functions
static void	setConnection (QAShrAlgorithm ancestor, QAShrAlgorithm descendant)
	Connect two algorithms. More...

static void	closeConnection (QAShrAlgorithm ancestor, QAShrAlgorithm descendant)
	Disconnect two algorithms. More...

static bool	checkConnection (const QAShrAlgorithm ancestor, const QAShrAlgorithm descendant)
	Check if two algorithms are connected. More...

static bool	isRemovableConnection (const QAShrAlgorithm p1, const QAShrAlgorithm p2)
	Check if two algorithms are connected and the connection is removable. More...

static void	improveTree (QAlgorithm *leaf)
	Replace all removable connections, thus improving the tree performance. More...

static std::pair< QString, QVariant >	makePropagationRules (std::initializer_list< std::pair< QString, QString >> lst)
	Convenience method for writing PropagationRules. More...

Protected Member Functions
virtual void	setup ()
	Set of instructions to set up the algorithm. More...

virtual void	init ()
	Set of instructions to initialize the algorithm. More...

QAShrAlgorithm	findAncestor (const QAlgorithm *ancestor) const
	Find an ancestor. More...

QAShrAlgorithm	findAncestor (const QAShrAlgorithm ancestor) const
	Find an ancestor. More...

QAShrAlgorithm	findDescendant (const QAlgorithm *descendant) const
	Find an descendant. More...

QAShrAlgorithm	findDescendant (const QAShrAlgorithm descendant) const
	Find an descendant. More...

QAShrAlgorithm	findSharedThis () const
	Find a shared pointer to this instance. More...

Properties
bool	finished = false
	Whether the algorithm finished to run and outputs are ready. More...

bool	started = false
	Whether the algorithm started to run. More...

QACompletionMap	ancestors
	Map with ancestors and their completion. More...

QACompletionMap	descendants
	Map with descendants and their completion. More...

static quint32	print_counter = 1

QFuture< void >	result

QFutureWatcher< void >	watcher

Related Functions
(Note that these are not member functions.)
QAShrAlgorithm	operator>> (QAShrAlgorithm ancestor, QAShrAlgorithm descendant)
	Creates connections like setConnection(). More...

QAShrAlgorithm	operator<< (QAShrAlgorithm descendant, QAShrAlgorithm ancestor)
	Creates connections like setConnection(). More...

QDebug	operator<< (QDebug debug, const QAlgorithm &c)
	Send debugging information to a QDebug instance. More...

QDataStream &	operator<< (QDataStream &stream, const QAlgorithm &c)
	Store a QAlgorithm into a QDataStream. More...

QDataStream &	operator>> (QDataStream &stream, QAlgorithm &c)
	Loads a QAlgorithm from a QDataStream. More...

Detailed Description

Abstract class that implements a generic algorithm.

This is an abstract class that contains the generic logic of an algorithm. You need to subclass it to use it and reimplement the run() function, that will contain the core of your algorithm.

Some macros like QA_INPUT(), QA_OUTPUT(), QA_PARAMETER() come in handy to define inputs, outputs and parameters of your algorithm.

Algorithms can be easily allocated using their create() static method, provided that the macro QA_IMPL_CREATE is put in your subclass definition.

If you have more algorithms that need to run in sequence, you can connect them using setConnection() and the friendly operators operator<<(QAShrAlgorithm descendant, QAShrAlgorithm ancestor) and operator>>(QAShrAlgorithm ancestor, QAShrAlgorithm descendant). Connections no more needed can be closed using closeConnection().

Generally you should use the methods serialExecution() (using the same thread) or parallelExecution() (using as many thread as possible) to run the whole algorithm tree. The connections you established between algorithms take care of passing outputs and parameters from parents to children; this is controlled by the so called PropagationRules. This is basically a map of strings to strings, where the name of parent's property is mapped to its children's destination property. The rules are as follows:

if no entry corresponds to parent's output property, then it is passed to a child only if it has an input property with the same name;
a parent's output property is passed to a child's input property with the name given by the PropagationRules;
a parent's parameter is passed to a child's input property or parameter only if there is an entry in the PropagationRules, otherwise parameters are not shared. The PropagationRules can be created using the static method makePropagationRules().

Every algorithm will have a boolean parameter called KeepInput. If this property is set to true the input is not freed until this instance is destroyed. Otherwise the input values are set to QVariant() as soon as the computation ends, and the connection with children is closed as soon as properties have been passed to them.

Every algorithm has also a ParallelExecution property (not to be confused with the method with the same name). This is a boolean value stating whether its children will be run in a different thread or in the same one. Forcing serial execution only for some connections can be useful if an algorithm's output is huge and can be processed immediately by its children.

An algorithm may also have multiple parents; in this case it is good for children algorithms to have a container to store all parents' outputs. This can be achieved declaring the children's inputs with the macros QA_INPUT_LIST() (for faster connections) or QA_INPUT_VEC() (for contiguous memory) instead of QA_INPUT().

Definition at line 96 of file QAlgorithm.h.

Constructor & Destructor Documentation

QAlgorithm::QAlgorithm ( QObject * parent = Q_NULLPTR )

Constructor.

Simply calls inherited classes' constructors and registers meta types used in the QAlgorithm class.

Definition at line 113 of file QAlgorithm.cpp.

                                       : QObject(parent), QRunnable()
 {
     qRegisterMetaType<QAPropertyMap>();
     qRegisterMetaType<QAPropagationRules>();
     qRegisterMetaType<QAShrAlgorithm>();
 }

Member Function Documentation

void QAlgorithm::abort ( QString message = "Unknown Error" ) const

slot

Emit the given error signal.

Typical use case for this function is to propagate an error from connected algorithms. Indeed it is, by default, connected to their raise() signal.

See Also: raise, setConnection

Definition at line 303 of file QAlgorithm.cpp.

Referenced by closeConnection(), and setConnection().

 {
     Q_EMIT raise(message);
 }

bool QAlgorithm::allInputsReady ( ) const

Checks if the algorithm is ready to run.

This function scan the ancestors and returns whether they all have finished their computations.

Returns: Whether every ancestor finished running.

Definition at line 46 of file QAlgorithm.cpp.

Referenced by parallelExecution(), and serialExecution().

 {
     return !getAncestors().values().contains(false);
 }

bool QAlgorithm::checkConnection	(	const QAShrAlgorithm	ancestor,
		const QAShrAlgorithm	descendant
	)

static

Check if two algorithms are connected.

This function simply checks if the given algorithms have previously been connected, for example using setConnection(), operator<<() or operator>>().

Parameters

[in]	ancestor	Shared pointer to an algorithm, that you want to check whether it is parent to descendant.
[in]	descendant	Shared pointer to an algorithm, that you want to check whether it is child to ancestor.

Returns: Whether ancestor is the parent of descendant.

See Also: setConnection, closeConnection

Definition at line 446 of file QAlgorithm.cpp.

Referenced by isRemovableConnection().

 {
     return ancestor->getDescendants().contains(descendant) && descendant->getAncestors().contains(ancestor);
 }

void QAlgorithm::closeConnection	(	QAShrAlgorithm	ancestor,
		QAShrAlgorithm	descendant
	)

static

Disconnect two algorithms.

This function does the opposite of setConnection().

Parameters

[in]	ancestor	Shared pointer to an algorithm, that you want to disconnect from its child descendant.
[in]	descendant	Shared pointer to an algorithm, that you want to disconnect from its parent ancestor.

See Also: setConnection, checkConnection

Definition at line 438 of file QAlgorithm.cpp.

Referenced by propagateExecution().

 {
     ancestor->descendants.remove(descendant);
     descendant->ancestors.remove(ancestor);
     disconnect(ancestor.data(), &QAlgorithm::raise, descendant.data(), &QAlgorithm::abort);
     disconnect(descendant.data(), &QAlgorithm::raise, ancestor.data(), &QAlgorithm::abort);
 }

QAShrAlgorithm QAlgorithm::findAncestor ( const QAlgorithm * ancestor ) const

protected

Find an ancestor.

Scans the ancestors of this algorithm looking for the given ancestor. If nothing is found returns a null shared pointer.

Parameters

[in] ancestor Pointer to the ancestor to be found.

Returns: Shared pointer to the requested ancestor, if any, or a null shared pointer otherwise.

See Also: findAncestor(QAShrAlgorithm), findDescendant, findSharedThis

Definition at line 61 of file QAlgorithm.cpp.

Referenced by findAncestor().

 {
     foreach(auto& shr_ancestor, getAncestors().keys())
     {
         if (shr_ancestor == ancestor)
         {
             return shr_ancestor;
         }
     }
     return QAShrAlgorithm();
 }

QAShrAlgorithm QAlgorithm::findAncestor ( const QAShrAlgorithm ancestor ) const

protected

Find an ancestor.

This is an overloaded method of findAncestor(QAlgorithm*).

Parameters

[in] ancestor Shared pointer to the ancestor to be found.

Returns: Shared pointer to the requested ancestor, if any, or a null shared pointer otherwise.

See Also: findAncestor(QAlgorithm*), findDescendant, findSharedThis

Definition at line 73 of file QAlgorithm.cpp.

 {
     return findAncestor(ancestor.data());
 }

QAShrAlgorithm QAlgorithm::findDescendant ( const QAlgorithm * descendant ) const

protected

Find an descendant.

Scans the descendants of this algorithm looking for the given descendant. If nothing is found returns a null shared pointer.

Parameters

[in] descendant Pointer to the descendant to be found.

Returns: Shared pointer to the requested descendant, if any, or a null shared pointer otherwise.

See Also: findAncestor, findDescendant(QAShrAlgorithm), findSharedThis

Definition at line 78 of file QAlgorithm.cpp.

Referenced by findDescendant().

 {
     foreach(auto& shr_descendant, getDescendants().keys())
     {
         if (shr_descendant == descendant)
         {
             return shr_descendant;
         }
     }
     return QAShrAlgorithm();
 }

QAShrAlgorithm QAlgorithm::findDescendant ( const QAShrAlgorithm descendant ) const

protected

Find an descendant.

This is an overloaded method of findAncestor(QAlgorithm*).

Parameters

[in] descendant Shared pointer to the descendant to be found.

Returns: Shared pointer to the requested descendant, if any, or a null shared pointer otherwise.

See Also: findAncestor, findDescendant(QAlgorithm*), findSharedThis

Definition at line 90 of file QAlgorithm.cpp.

 {
     return findDescendant(descendant.data());
 }

QAShrAlgorithm QAlgorithm::findSharedThis ( ) const

protected

Find a shared pointer to this instance.

Scans the descendants and ancestors of this algorithm looking for a shared pointer to this instance. The first pointer found is returned, if any, otherwise a null shared pointer is returned.

No shared pointer is created by this function.

Returns: Shared pointer to this instance, if any, or a null shared pointer otherwise.

See Also: findAncestor, findDescendant

Definition at line 95 of file QAlgorithm.cpp.

Referenced by flattenTree(), and propagateExecution().

 {
     // Check among the descendants
     foreach(auto descendant, getDescendants().keys())
     {
         auto shr_this = descendant->findAncestor(this);
         if(!shr_this.isNull()) return shr_this;
     }
     // Otherwise check among the ancestors
     foreach(auto ancestor, getAncestors().keys())
     {
         auto shr_this = ancestor->findDescendant(this);
         if(!shr_this.isNull()) return shr_this;
     }
     // If nothing was found return null shared pointer
     return QAShrAlgorithm();
 }

QAFlatRepresentation QAlgorithm::flattenTree ( QAFlatRepresentation tree = QAFlatRepresentation() ) const

Creates a flat representation of the algorithm tree.

A flat representation of the algorithm is a map with:

key, an algorithm shared pointer (father)
values, the set of shared pointer algorithms that are direct children of key

flattenTree() method can be called with no arguments on any node of an algorithm tree to generate such representation.

When flattenTree() is called with a flat representation tree as argument, then it appends the new representation to the given one. This behaviour is internally used by the flattenTree() method and is probably of no use for the common user.

Parameters

[in] tree Optional representation to include in the output.

Returns: The flat representation of the algorithm tree structure.

See Also: printTree, printGraph, improveTree

Definition at line 400 of file QAlgorithm.cpp.

Referenced by improveTree(), printGraph(), and printTree().

 {
     // Search for a shared pointer attached to this instance
     auto keysList = tree.keys();
     // Check if the function has already been applied to this
     auto shr_this_it = std::find_if(keysList.begin(), keysList.end(), [this](auto& ptr)
                                     {return ptr == this;}
                                     );
     if (shr_this_it == keysList.end())
     {
         // Otherwise link each descendant to this in the map
         auto shr_this = findSharedThis();
         if(shr_this.isNull()) qWarning() << "This instance has no properly set connection, flattenTree will not work";
         else
         {
             // Insert shr_this as new key in the map
             tree[shr_this] = QSet<QAShrAlgorithm>();
             // Append each descendant to it
             for (auto descendant: getDescendants().keys()) tree[shr_this] << descendant;
             // Recursive step: apply the function to each relative not yet scanned
             for (auto relative: getDescendants().keys()+getAncestors().keys())
             {
                 if (!tree.contains(relative)) tree = relative->flattenTree(tree);
             }
         }
     }
     else qWarning() << "flattenTree: possible loop";
     return tree;
 }

QACompletionMap QAlgorithm::getAncestors ( ) const

Get the value of ancestors.

Returns: The value of this algorithm's ancestors.

See Also: ancestors, descendants

Definition at line 51 of file QAlgorithm.cpp.

Referenced by allInputsReady(), findAncestor(), findSharedThis(), flattenTree(), parallelExecution(), propagateExecution(), and serialExecution().

 {
     return ancestors;
 }

QACompletionMap QAlgorithm::getDescendants ( ) const

Get the value of descendants.

Returns: The value of this algorithm's descendants.

See Also: ancestors, descendants

Definition at line 56 of file QAlgorithm.cpp.

Referenced by findDescendant(), findSharedThis(), flattenTree(), and propagateExecution().

 {
     return descendants;
 }

bool QAlgorithm::getInput ( QAShrAlgorithm parent )

virtual

Load inputs from parent's outputs.

This function assigns any parent's output or parameter properties to this instance's input or parameter properties sharing the same name. In case you want to connect a parent's property to a property with different name, you can use the PropagationRules. Taking parameters from parent is allowed only if the parent's parameter name is explicitly mentioned among the PropagationRules.

Returns: Whether inputs have been loaded successfully.

See Also: makePropagationRules

Definition at line 187 of file QAlgorithm.cpp.

 {
     // Create an alias to this for better readability
     auto child = this;
     // Scan parent's properties and grab all the possible outputs and parameters
     for(int k = 0; k < parent->metaObject()->propertyCount(); ++k)
     {
         QString parentPropName = parent->metaObject()->property(k).name();
         // Get the parent's property base name
         // Both output and parameter properties are checked
         QString parentPropBaseName;
         if(parentPropName.startsWith(QA_OUT))
         {
             // Output property
             parentPropBaseName = parentPropName.mid(strlen(QA_OUT));
         }
         else if(parentPropName.startsWith(QA_PAR))
         {
             // Parameter
             parentPropBaseName = parentPropName.mid(strlen(QA_PAR));
         }
         else continue;
         // Get the child's property base name, based on PropagationRules values
         QString childPropBaseName;
         if(!getPropagationRules().contains(parentPropBaseName))
         {
             childPropBaseName = parentPropBaseName;
         }
         else
         {
             // The values associated with the given key
             auto values = getPropagationRules().values(parentPropBaseName);
             if(values.size() > 1)
             {
                 // If there are more than one value, then use the first one that contain the parent object name
                 childPropBaseName = values.filter(parent->objectName()).first();
             }
             else
             {
                 childPropBaseName = values.first();
             }
         }
         // Parameters are sent only if they are explicitly mentioned in the PropagationRules
         if(parentPropName.startsWith(QA_PAR) && !getPropagationRules().contains(parentPropBaseName))
         {
             continue;
         }
         // Check if the property is in child's input or parameter properties
         for(int i = 0; i < child->metaObject()->propertyCount(); ++i)
         {
             QString childPropName = child->metaObject()->property(i).name();
             // If the current property corresponds to an input with the same base name as before,
             // then assign it; the same will be done also for parameters.
             if(childPropName == QA_IN+childPropBaseName || childPropName == QA_PAR+childPropBaseName)
             {
                 QVariant parentProp = parent->property(parentPropName.toStdString().c_str());
                 if(parentProp.isValid())
                 {
                     if(!child->setProperty(childPropName.toStdString().c_str(), parentProp))
                     {
                         qWarning() << "getInput():" << childPropName << "failed to set for" << child->printName();
                         return false;
                     }
                 }
                 else
                 {
                     qWarning() << "getInput():" << parentPropName << "failed to read for" << parent->printName();
                     return false;
                 }
             }
         }
     }
     return true;
 }

void QAlgorithm::improveTree ( QAlgorithm * leaf )

static

Replace all removable connections, thus improving the tree performance.

It actually force any pair of removably-connected algorithms to run in the same thread. If KeepInput is set to false for the parent, and properties are moved insted of copied to the child instance, the improvement is high, since there is almost no waste in memory and time. Indeed the parent instance will be deleted as soon as it becomes useless, and its properties are directly exploited by the child instance without deep copying them; furthermore time consumption is limited by running on the same thread.

Note: This function is still experimental, since it's not been much tested.

Parameters

[in] leaf Pointer to an algorithm belonging to the tree to improve.

See Also: isRemovableConnection

Definition at line 549 of file QAlgorithm.cpp.

 {
     auto flatMap = leaf->flattenTree();
     QMap<QAShrAlgorithm, QList<QAShrAlgorithm>> replacements;
     foreach (auto ptr, flatMap.uniqueKeys())
     {
         foreach(auto child, flatMap[ptr])
         {
             if (QAlgorithm::isRemovableConnection(ptr, child))
             {
                 // Insert a new replacement (assuming uniqueness of flat map keys)
                 replacements[ptr] << child;
             }
         }
     }
     // From the set of removable connection, link the pairs that form a removable connection all together
     bool some_changes = true;
     while(some_changes)
     {
         some_changes = false;
         foreach(auto p1, replacements.keys())
         {
             // Take the last element in the list of removable connections
             auto p2 = replacements[p1].last();
             // If it has its own removable connections, add them to p1's
             if (replacements.contains(p2))
             {
                 replacements[p1] += replacements.take(p2);
                 some_changes = true;
                 break; // recompute keys after any change
             }
         }
     }
     // Create the envelopes for each replacement
     foreach(QList<QAShrAlgorithm> nodes, replacements.values())
     {
         // Tell each node, except the last, to serially execute its children
         nodes.removeLast();
         foreach(auto node, nodes)
         {
             node->setParallelExecution(false);
         }
     }
 }

virtual void QAlgorithm::init ( )

inlineprotectedvirtual

Set of instructions to initialize the algorithm.

Any subclass that needs to preallocate variables or configure anything should do that reimplementing this function.

Note: This is automatically called by the create() function, after setting any parameter; if you want to manually allocate a subclass instance, you should call this function by yourself.; If you need to set things up before the algorithm parameters has been given, you can reimplement the function setup().

See Also: setup, setParameters, QA_IMPL_CREATE

Definition at line 234 of file QAlgorithm.h.

234 {};

bool QAlgorithm::isFinished ( ) const

Get the value of finished.

Returns: Whether the algorithm finished running.

See Also: started, finished, isStarted

Definition at line 24 of file QAlgorithm.cpp.

 {
     return finished;
 }

bool QAlgorithm::isRemovableConnection	(	const QAShrAlgorithm	p1,
		const QAShrAlgorithm	p2
	)

static

Check if two algorithms are connected and the connection is removable.

This function checks if two algorithms are connected using checkConnection(); if so, it checks also if it is a removable connection, that is: a connection where the parent has only one child, and the child has only one parent. It is called removable because parent and child can be put together in a single algorithm, without changing the overall behavior.

Parameters

[in]	ancestor	Shared pointer to an algorithm, that you want to check whether it is parent to descendant.
[in]	descendant	Shared pointer to an algorithm, that you want to check whether it is child to ancestor.

Returns: Whether there is a removable connection between ancestor and descendant.

See Also: improveTree

Definition at line 451 of file QAlgorithm.cpp.

Referenced by improveTree().

 {
     if (QAlgorithm::checkConnection(p2, p1))
     {
         return (p2->getDescendants().count() == 1) && (p1->getAncestors().count() == 1);
     }
     else if (QAlgorithm::checkConnection(p1, p2))
     {
         return (p1->getDescendants().count() == 1) && (p2->getAncestors().count() == 1);
     }
     else return false;
 }

bool QAlgorithm::isStarted ( ) const

Get the value of started.

Returns: Whether the algorithm started running.

See Also: started, finished, isFinished

Definition at line 29 of file QAlgorithm.cpp.

 {
     return started;
 }

Q_SIGNAL void QAlgorithm::justFinished ( )

signal

Signal emitted on algorithm's end.

Note: By default this signal is connected to the slot propagateExecution(), to make descendants run as this algorithm ends.

See Also: propagateExecution, finished

Referenced by setFinished(), and setup().

Q_SIGNAL void QAlgorithm::justStarted ( )

signal

Signal emitted on algorithm's start.

See Also: started

Referenced by setStarted().

std::pair< QString, QVariant > QAlgorithm::makePropagationRules ( std::initializer_list< std::pair< QString, QString >> lst )

static

Convenience method for writing PropagationRules.

Parameters

[in] lst Something like {{"Out1","In1"},{"Out2","In2"}}

Returns: A pair that can be used to construct a QAPropertyMap from an initializer list.

Definition at line 386 of file QAlgorithm.cpp.

 {
     return std::pair<QString, QVariant>({"PropagationRules", QVariant::fromValue(QAPropagationRules(pairs))});
 }

void QAlgorithm::parallelExecution ( )

slot

Start computing the algorithm tree on different threads.

This function makes the entire algorithm tree run on threads other than the one who calls it. No matter which level the function is called on, the whole algorithm tree will be computed.

Note: The calling function will NOT freeze waiting for completion.

See Also: serialExecution()

Definition at line 262 of file QAlgorithm.cpp.

 {
     // Check if every ancestor has finished
     if(allInputsReady())
     {
         // Perform the core part of the algorithm is a separate thread
         setStarted();
         result = QtConcurrent::run(this, &QAlgorithm::run);
         watcher.setFuture(result);
     }
     else
     {
         // Run those not started
         for(const auto& ancestor: getAncestors().keys(false))
         {
             // Only start processes not already started
             if(!ancestor->isStarted()) ancestor->parallelExecution();
         }
     }
 }

void QAlgorithm::printGraph ( const QString & path = QString() ) const

Create a GraphViz diagram of the algorithm tree.

Mostly useful for debugging purposes, this function the graphviz executable as an external process to generate the visual representation of the algorithm tree.

Note: This feature is still experimental. It has not been tested and lacks generality.

Parameters

[in] path Path to the output file.

Definition at line 308 of file QAlgorithm.cpp.

 {
     QFile dotFile;
     QString outFileName;
     if (path.isEmpty())
     {
         dotFile.setFileName(QDir::home().absoluteFilePath("QAlgorithmTree.gv"));
         outFileName = QDir::home().absoluteFilePath("QAlgorithmTree.svg");
     }
     else
     {
         dotFile.setFileName(path);
         QStringList svgpath = path.split(".");
         svgpath.removeLast();
         outFileName = svgpath.join(".")+".svg";
     }
     if (!dotFile.open(QFile::WriteOnly)) Q_EMIT raise("Cannot write graph to given file");
     else
     {
         QTextStream dot(&dotFile);
         QLocale nospace;
         nospace.setNumberOptions(QLocale::NumberOption::OmitGroupSeparator);
         dot << "digraph g{\n";
         auto flatMap = flattenTree();
         // Save node labels
         foreach(auto alg, flatMap.keys())
         {
             QString id = nospace.toString(quint64(alg.data()));
             QString idspace = QLocale().toString(quint64(alg.data()));
             QString name = alg->metaObject()->className();
             QString nickname = alg->objectName();
             QString dotstring = "var"+id.replace(" ", "")+"[label=\""+name+"\\nID "+idspace;
             if(!nickname.isEmpty()) dotstring += "\\nNick: "+nickname;
             dotstring += "\"];\n";
             dot << dotstring;
         }
         // Save connections between nodes
         foreach(auto parent, flatMap.keys())
         {
             QString parentName = "var" + nospace.toString(quint64(parent.data()));
             foreach(auto child, flatMap[parent])
             {
                 QString childName = "var" + nospace.toString(quint64(child.data()));
                 dot << parentName << " -> " << childName << "\n";
             }
         }
         dot << "}\n";
         dotFile.close();
         // Convert dot file to svg
         QStringList cmdArgs =
         {dotFile.fileName(), "-Tsvg", "-o", outFileName}
         ;
         int r = QProcess::execute("/usr/local/bin/circo", cmdArgs);
         if (r == -1)
         {
             qWarning("%s", "The dot process crashed");
         }
         else if (r == -2)
         {
             qWarning("%s", "Cannot start the dot process");
         }
         else
         {
             r = QProcess::execute("/bin/rm",
                                   {dotFile.fileName()}
                                   );
             if (r == -1)
             {
                 qWarning("%s", "The rm process crashed");
             }
             else if (r == -2)
             {
                 qWarning("%s", "Cannot start the rm process");
             }
         }
     }
 }

QString QAlgorithm::printName ( ) const

Returns name, memory address and class name of the algorithm.

This function is mostly useful for debugging purposes.

Returns: A string composed by memory address, class name and object name of the algotithm.

Definition at line 391 of file QAlgorithm.cpp.

Referenced by operator<<(), and operator>>().

 {
     QString msg;
     msg += QString(metaObject()->className()) + " ";
     msg += QLocale().toString(qlonglong(this)) + " ";
     if (!objectName().isEmpty()) msg += objectName();
     return msg;
 }

void QAlgorithm::printTree ( const QAFlatRepresentation & tree = QAFlatRepresentation() ) const

Outputs a text representation of the algorithm tree.

Actually sends to the standard output the flat representation of the given tree, printed as such in a key-value structure.

Parameters

[in] tree The tree to be visualized; if empty the function will use the output of flattenTree() called on this instance.

See Also: flattenTree

Definition at line 531 of file QAlgorithm.cpp.

 {
     auto _printTree = [](decltype(tree) map)
     {
         foreach(auto key, map.keys())
         {
             qInfo() << "key" << key->printName();
             foreach(auto value, map[key])
             {
                 qInfo() << "\tvalue" << value->printName();
             }
         }
     }
     ;
     if (tree.isEmpty()) _printTree(flattenTree());
     else _printTree(tree);
 }

void QAlgorithm::propagateExecution ( )

slot

Execute descendants.

This functions changes values to ancestors and descendants, making connected algorithms know that this instance finished running. Then passes outputs and parameters to every descendant.

If KeepInput parameter is set to false, the inputs are invalidated and the connection with descendants is closed. This will deallocate this object as soon as it ends its computation and sends the results.

Finally, serialExecution() or parallelExecution() is called on each descendant according to the value of ParallelExecution.

Note: Generally there is no need for the users to directly call this function. It is by default connected to the justFinished() signal.

See Also: serialExecution, parallelExecution

Definition at line 153 of file QAlgorithm.cpp.

Referenced by setup().

 {
     auto shr_this = findSharedThis();
     if(!shr_this.isNull())
     {
         // Notify ancestors
         foreach(auto ancestor, getAncestors().keys()) ancestor->descendants[shr_this] = true;
         // Notify descendants, transfer output to and execute them
         foreach(auto descendant, getDescendants().keys())
         {
             descendant->ancestors[shr_this] = true;
             descendant->getInput(shr_this);
             if(!descendant->getKeepInput())
             {
                 QAlgorithm::closeConnection(shr_this, descendant);
                 // Set each input property to null
                 // useful if input has been received with implicit sharing
                 for(int k = 0; k < metaObject()->propertyCount(); ++k)
                 {
                     if(QString(metaObject()->property(k).name()).startsWith(QA_IN))
                     {
                         setProperty(metaObject()->property(k).name(), QVariant());
                     }
                 }
             }
             if(!descendant->isStarted())
             {
                 if (getParallelExecution()) descendant->parallelExecution();
                 else descendant->serialExecution();
             }
         }
     }
 }

Q_SIGNAL void QAlgorithm::raise ( QString message ) const

signal

Signal emitted whenever an error occurs.

This class emits the raise signal whenever an internal error occurs. This behaviour replaces the traditional exception throwing, allowing the user to easily handle errors in Qt event loop. Indeed each subclass should use the same convention, and every caller should handle and possibly retransmit the raise signal.

Parameters

[in] message The error description.

Referenced by closeConnection(), and setConnection().

virtual void QAlgorithm::run ( )

pure virtual

Core part of the algorithm, to be reimplemented in subclasses.

For more information see class QAlgorithm description.

Referenced by parallelExecution(), and serialExecution().

void QAlgorithm::serialExecution ( )

slot

Start computing the algorithm tree on the calling thread.

This function makes the entire algorithm tree run on the same thread that calls it. No matter which level the function is called on, the whole algorithm tree will be computed.

Note: The calling function will freeze waiting for completion.

See Also: parallelExecution()

Definition at line 283 of file QAlgorithm.cpp.

 {
     // Check if every ancestor has finished
     if(!allInputsReady())
     {
         // Run those not started
         for(const auto& ancestor: getAncestors().keys(false))
         {
             // Only start processes not already started
             if(!ancestor->isStarted()) ancestor->serialExecution();
         }
     }
     // Set the ParallelExecution policy to false
     setParallelExecution(false);
     // Perform the core part of the algorithm in the same thread
     setStarted();
     run();
     setFinished();
 }

void QAlgorithm::setConnection	(	QAShrAlgorithm	ancestor,
		QAShrAlgorithm	descendant
	)

static

Connect two algorithms.

Modifies the completion maps of both algorithms and reciprocally connect them through the raise() signal, for error propagation throughout the whole algorithm tree.

Parameters

[in]	ancestor	Shared pointer to an algorithm, that you want to connect to its child descendant.
[in]	descendant	Shared pointer to an algorithm, that you want to connect to its parent ancestor.

See Also: closeConnection, checkConnection

Definition at line 430 of file QAlgorithm.cpp.

Referenced by operator>>().

 {
     ancestor->descendants[descendant] = descendant->isFinished();
     descendant->ancestors[ancestor] = ancestor->isFinished();
     connect(ancestor.data(), &QAlgorithm::raise, descendant.data(), &QAlgorithm::abort, Qt::QueuedConnection);
     connect(descendant.data(), &QAlgorithm::raise, ancestor.data(), &QAlgorithm::abort, Qt::QueuedConnection);
 }

void QAlgorithm::setFinished ( )

Set the algorithm as comleted and signals it.

This is actually the setter method for finished and emits justFinished().

It is not meant to be directly used in the code; it is called by serialExecution() and parallelExecution(), use these functions instead.

See Also: finished, isFinished, started

Definition at line 40 of file QAlgorithm.cpp.

Referenced by serialExecution(), and setup().

 {
     finished = true;
     Q_EMIT justFinished();
 }

void QAlgorithm::setParameters ( const QAPropertyMap & parameters )

virtual

Set parameters for the algorithm.

The given name-value parameter pairs are assigned to parameters or input properties.

Note: This is automatically called by the create() function, after calling setup() but before init(); if you want to manually allocate a subclass instance, you should call this function by yourself.

Parameters

[in] parameters Name-value parameter/input pairs.

See Also: setup, init, QA_IMPL_CREATE

Definition at line 120 of file QAlgorithm.cpp.

 {
     // Scan the object properties
     for(const QString& PropName: parameters.keys())
     {
         bool set = false;
         for(int k = 0; k < metaObject()->propertyCount(); ++k)
         {
             if(metaObject()->property(k).name() == QA_PAR + PropName ||
                metaObject()->property(k).name() == QA_IN + PropName)
             {
                 // This property is a parameter or an input
                 // Write the desired value in the property
                 if (!setProperty(metaObject()->property(k).name(), parameters.value(PropName)))
                 {
                     qWarning() << "Cannot set parameter/input" << PropName;
                 }
                 set = true;
             }
         }
         if(!set) qWarning() << "Trying to set" << PropName << "but it is not among object's properties";
     }
 }

void QAlgorithm::setStarted ( )

Set the algorithm as started and signals it.

This is actually the setter method for started and emits justStarted().

It is not meant to be directly used in the code; it is called by serialExecution() and parallelExecution(), use these functions instead.

See Also: started, isStarted, finished

Definition at line 34 of file QAlgorithm.cpp.

Referenced by parallelExecution(), and serialExecution().

 {
     started = true;
     Q_EMIT justStarted();
 }

void QAlgorithm::setup ( )

protectedvirtual

Set of instructions to set up the algorithm.

Any subclass that needs to preallocate variables or configure anything should do that reimplementing this function.

Note: This is automatically called by the create() function, before setting any parameter; if you want to manually allocate a subclass instance, you should call this function by yourself.; If you need to set things up after the algorithm parameters has been given, you can reimplement the function init().

See Also: init, setParameters, QA_IMPL_CREATE

Definition at line 144 of file QAlgorithm.cpp.

 {
     // Prevent the QThreadPool to delete a parent instance
     setAutoDelete(false);
     // Make internal connections
     connect(this, &QAlgorithm::justFinished, this, &QAlgorithm::propagateExecution, Qt::AutoConnection);
     connect(&watcher, &QFutureWatcher<void>::finished, this, &QAlgorithm::setFinished, Qt::AutoConnection);
 }

Friends And Related Function Documentation

QAShrAlgorithm operator<<	(	QAShrAlgorithm	descendant,
		QAShrAlgorithm	ancestor
	)

Definition at line 470 of file QAlgorithm.cpp.

 {
     ancestor >> descendant;
     return ancestor;
 }

QDebug operator<<	(	QDebug	debug,
		const QAlgorithm &	c
	)

Definition at line 476 of file QAlgorithm.cpp.

 {
     QDebugStateSaver saver(debug);
     const QMetaObject* obj = c.metaObject();
     
     // Write the algorithm class name
     debug << endl << "------------------------------" << c.printName() << "subclass of QAlgorithm" << endl;
     
     // Write the input properties of the algorithm
     debug << "Algorithm with input:" << endl;
     for(int k = 0; k < obj->propertyCount(); k++)
     {
         QMetaProperty prop = obj->property(k);
         // Check whether the current property's name starts with "algin_"
         QString propName = prop.name();
         if(propName.startsWith(QA_IN))
         {
             propName.remove(QA_IN);
             debug << propName.rightJustified(30,' ',true) << "\t" << prop.read(&c) << endl;
         }
     }
     
     // Write the parameters of the algorithm
     debug << "Algorithm with parameters:" << endl;
     for(int k = 0; k < obj->propertyCount(); k++)
     {
         QMetaProperty prop = obj->property(k);
         // Check whether the current property's name starts with "algin_"
         QString propName = prop.name();
         if(propName.startsWith(QA_PAR))
         {
             propName.remove(QA_PAR);
             debug << propName.rightJustified(30,' ',true) << "\t" << prop.read(&c) << endl;
         }
     }
     
     // Write the output properties of the algorithm
     debug << "Algorithm with output:" << endl;
     for(int k = 0; k < obj->propertyCount(); k++)
     {
         QMetaProperty prop = obj->property(k);
         // Check whether the current property's name starts with "algout_"
         QString propName = prop.name();
         if(propName.startsWith(QA_OUT))
         {
             propName = propName.remove(QA_OUT);
             debug << propName.rightJustified(30,' ',true) << "\t" << prop.read(&c) << endl;
         }
     }
     
     debug << "------------------------------" << endl;
     
     return debug;
 }

QDataStream & operator<<	(	QDataStream &	stream,
		const QAlgorithm &	c
	)

This function is useful to quickly save an algorithm instance to file. It internally saves all the input and output properties, and all the parameters. The saved information can be retrieved by the converse operator>>(QDataStream&, QAlgorithm&).

The behaviour can be customized by subclasses.

See Also: operator>>(QDataStream&, QAlgorithm&)

Definition at line 594 of file QAlgorithm.cpp.

 {
     QAPropertyMap properties;
     for(int k = 0; k < c.metaObject()->propertyCount(); k++)
     {
         QMetaProperty prop = c.metaObject()->property(k);
         QString propName = prop.name();
         QVariant propValue = prop.read(&c);
         if(propValue.isValid() &&
            (propName.startsWith(QA_IN) || propName.startsWith(QA_OUT) || propName.startsWith(QA_PAR)))
             properties.insert(propName, propValue);
     }
     return (stream << properties);
 }

QAShrAlgorithm operator>>	(	QAShrAlgorithm	ancestor,
		QAShrAlgorithm	descendant
	)

Definition at line 464 of file QAlgorithm.cpp.

 {
     QAlgorithm::setConnection(ancestor, descendant);
     return descendant;
 }

QDataStream & operator>>	(	QDataStream &	stream,
		QAlgorithm &	c
	)

This function is useful to quickly load an algorithm instance from file.

The behaviour can be customized by subclasses.

See Also: operator<<(QDataStream&, const QAlgorithm&)

Definition at line 609 of file QAlgorithm.cpp.

 {
     QAPropertyMap properties;
     stream >> properties;
     for(int k = 0; k < c.metaObject()->propertyCount(); k++)
     {
         QMetaProperty prop = c.metaObject()->property(k);
         QString propName = prop.name();
         if(properties.contains(propName))
         {
             if (!prop.write(&c, properties.values(propName)))
             {
                 qWarning() << c.printName() << "Unable to write property value, report to the QAlgorithm developer";
             }
         }
     }
     return stream;
 }

Property Documentation

QACompletionMap QAlgorithm::ancestors

read

Map with ancestors and their completion.

Map that contains information about the ancestors of the algorithm; each key is a shared pointer to an ancestor of this algorithm, the values are booleans stating whether the algorithm is finished or not.

Note: This is a read-only property. You can have access to this property value through the const getter getAncestors().

You can set ancestors through the functions mentioned in the see-also section.

See Also: setConnection, closeConnection, operator<<, operator>>

Definition at line 107 of file QAlgorithm.h.

Referenced by getAncestors().

QACompletionMap QAlgorithm::descendants

read

Map with descendants and their completion.

Map that contains information about the descendants of the algorithm; see ancestors for a description of the mapped values.

Note: This is a read-only property. You can have access to this property value through the const getter getDescendants().

You can set descendants through the functions mentioned in the see-also section.

See Also: setConnection, closeConnection, operator<<, operator>>

Definition at line 108 of file QAlgorithm.h.

Referenced by getDescendants().

bool QAlgorithm::finished = false

read

Whether the algorithm finished to run and outputs are ready.

The signal justFinished() is emitted whenever this property changes its value and the algorithm reach completion.

Note: This is a read-only property. You can have access to this property value through the const getter isFinished().

See Also: setFinished, isFinished, started

Definition at line 105 of file QAlgorithm.h.

Referenced by isFinished(), and setFinished().

quint32 QAlgorithm::print_counter = 1

static

Definition at line 195 of file QAlgorithm.h.

QFuture<void> QAlgorithm::result

Definition at line 197 of file QAlgorithm.h.

Referenced by parallelExecution().

bool QAlgorithm::started = false

read

Whether the algorithm started to run.

The signal justStarted() is emitted whenever this property changes its value and the algorithm reach completion.

Note: This is a read-only property. You can have access to this property value through the const getter isStarted().

See Also: setStarted, isStarted, finished

Definition at line 106 of file QAlgorithm.h.

Referenced by isStarted(), and setStarted().

QFutureWatcher<void> QAlgorithm::watcher

Definition at line 198 of file QAlgorithm.h.

Referenced by parallelExecution(), and setup().

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

/home/travis/build/DottD/QAlgorithm/Sources/QAlgorithm.h
/home/travis/build/DottD/QAlgorithm/Sources/QAlgorithm.cpp

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Property Documentation