API: Add pgm_is_child() and pgm_is_parent().

This patch adds two new APIs to PGM: pgm_is_child()
and pgm_is_parent() for convenience to the programmer.
These functions can already be supported by a combination
of other PGM API calls, but it is troublesome for such
a simple query.

2 files changed, 102 insertions, 8 deletions

diff --git a/include/pgm.h b/include/pgm.h
index 671bb9f..27cae67 100644
--- a/include/pgm.h
+++ b/include/pgm.h
@@ -177,7 +177,7 @@ int pgm_init_graph(graph_t* graph, const char* graph_name);
 /*
    Prints the graph in dot format to the provided file descriptor.
      [in] graph: Graph
-         [in] file: File descriptor
+     [in] file: File descriptor
    Return: 0 on success. -1 on error.
  */
 int pgm_print_graph(graph_t graph, FILE* out);
@@ -411,16 +411,59 @@ int pgm_get_nr_consume(edge_t edge);
 int pgm_get_nr_threshold(edge_t edge);
 
 /*
+   Query to see if 'query' is a child of 'node'.
+     [in] node:  possible parent of 'query'
+     [in] query: possible child of 'node'
+   Return:
+     1 if 'query' is a child of 'node'.
+     0 if 'query' is NOT a child of 'node'.
+     -1 if 'query' or 'node' is an invalid node, or
+       if 'query' and 'node' are from different graphs
+
+   Note: Explicit backedges are ignored.
+
+   Note: Beware that pgm_is_child() returns -1 on error,
+     so the code "if(pgm_is_child(..))" may introduce bugs
+     since the logic test does not distinguish between the
+     positive case and the error case.
+ */
+int pgm_is_child(node_t node, node_t query);
+
+/*
+   Query to see if 'query' is a parent of 'node'.
+     [in] node:  possible child of 'query'
+     [in] query: possible parent of 'node'
+   Return:
+     1 if 'query' is a parent of 'node'.
+     0 if 'query' is NOT a parent of 'node'.
+    -1 if 'query' or 'node' is an invalid node, or
+       if 'query' and 'node' are from different graphs
+
+   Note: Explicit backedges are ignored.
+
+   Note: Beware that pgm_is_parent() returns -1 on error,
+     so the code "if(pgm_is_parent(..))" may introduce bugs
+     since the logic test does not distinguish between the
+     positive case and the error case.
+ */
+int pgm_is_parent(node_t node, node_t query);
+
+/*
    Query to see if 'query' is an ancestor of 'node'.
      [in] node:  possible decendent of 'query'
      [in] query: possible ancestor of 'node'
    Return:
      1 if 'query' is an ancestor of 'node'.
      0 if 'query' is NOT an ancestor of 'node'.
-        -1 if 'query' or 'node' is an invalid node, or
+    -1 if 'query' or 'node' is an invalid node, or
        if 'query' and 'node' are from different graphs
 
-   Note: pgm_is_ancestor(n, q) === pgm_is_descendant(q, n)
+   Note: Explicit backedges are ignored.
+
+   Note: Beware that pgm_is_ancestor() returns -1 on error,
+     so the code "if(pgm_is_ancestor(..))" may introduce bugs
+     since the logic test does not distinguish between the
+     positive case and the error case.
  */
 int pgm_is_ancestor(node_t node, node_t query);
 
@@ -431,18 +474,23 @@ int pgm_is_ancestor(node_t node, node_t query);
    Return:
      1 if 'query' is an decendent of 'node'.
      0 if 'query' is NOT an decendent of 'node'.
-        -1 if 'query' or 'node' is an invalid node, or
+    -1 if 'query' or 'node' is an invalid node, or
        if 'query' and 'node' are from different graphs
 
-   Note: pgm_is_ancestor(n, q) === pgm_is_descendant(q, n)
+   Note: Explicit backedges are ignored.
+
+   Note: Beware that pgm_is_descendant() returns -1 on error,
+     so the code "if(pgm_is_descendant(..))" may introduce bugs
+     since the logic test does not distinguish between the
+     positive case and the error case.
  */
 int pgm_is_descendant(node_t node, node_t query);
 
 /*
    Check if a graph is a acyclic.
      [in] graph: Graph descriptor
-         [in] ignore_explicit_backedges: Ignore edges that were added
-              with pgm_init_backedge().
+     [in] ignore_explicit_backedges: Ignore edges that were added
+          with pgm_init_backedge().
    Return: 1 if graph is acyclic, 0 if it is not.
  */
 int pgm_is_dag(graph_t graph, int ignore_explicit_backedges = 1);
diff --git a/src/pgm.cpp b/src/pgm.cpp
index d66641f..122775e 100644
--- a/src/pgm.cpp
+++ b/src/pgm.cpp
@@ -2723,6 +2723,53 @@ out:
         return ret;
 }
 
+int pgm_is_parent(node_t node, node_t query)
+{
+        int ret = -1;
+        struct pgm_graph* g;
+        struct pgm_node* n;
+        struct pgm_node* q;
+
+        if(node.graph != query.graph)
+                goto out;
+        if(!is_valid_graph(node.graph))
+                goto out;
+
+        ret = 0;
+        if(node.node == query.node)
+        {
+                goto out;
+        }
+
+        g = &gGraphs[node.graph];
+        n = &g->nodes[node.node];
+        q = &g->nodes[query.node];
+
+        pthread_mutex_lock(&g->lock);
+        for(int i = 0; i < n->nr_in; ++i)
+        {
+                if(g->edges[n->in[i]].is_backedge)
+                {
+                        continue; // skip backedge
+                }
+
+                if(q == &g->nodes[g->edges[n->in[i]].producer])
+                {
+                        ret = 1;
+                        break;
+                }
+        }
+        pthread_mutex_unlock(&g->lock);
+
+out:
+        return ret;
+}
+
+int pgm_is_child(node_t node, node_t query)
+{
+        return pgm_is_parent(query, node);
+}
+
 static int is_ancestor(const struct pgm_graph* g,
         const struct pgm_node* n, const struct pgm_node* q,
         std::set<int>& visited)
@@ -2785,7 +2832,6 @@ int pgm_is_ancestor(node_t node, node_t query)
 
 out:
         return ret;
-
 }
 
 int pgm_is_descendant(node_t n, node_t query)