usnic: add graph utility code

This code is intended to support usNIC interface matching functionality.
We currently view that problem as essentially the "Assignment Problem"
(http://en.wikipedia.org/wiki/Assignment_problem), for which there are
many possible solution approaches, including flow-network analysis.  In
the future, we might transition to a more nuanced view of the problem
which would likely also be flow-network based.

To this end, the current code focuses on providing one major algorithm
to the core usnic BTL: `ompi_btl_usnic_solve_bipartite_assignment`.  It
also exposes several typical and necessary functions for constructing,
manipulating, and querying weighted, directed graphs.

Reviewed-by: Jeff Squyres <jsquyres@cisco.com>

cmr=v1.7.5:ticket=trac:4253

This commit was SVN r30847.

The following Trac tickets were found above:
  Ticket 4253 --> https://svn.open-mpi.org/trac/ompi/ticket/4253

ompi/mca/btl/usnic/Makefile.am

@@ -28,7 +28,8 @@ dist_ompidata_DATA = \
     help-mpi-btl-usnic.txt
 
 test_sources = \
-    test/btl_usnic_component_test.h
+    test/btl_usnic_component_test.h \
+    test/btl_usnic_graph_test.h
 
 sources = \
     btl_usnic_compat.h \
@@ -42,6 +43,8 @@ sources = \
     btl_usnic_endpoint.h \
     btl_usnic_frag.c \
     btl_usnic_frag.h \
+    btl_usnic_graph.h \
+    btl_usnic_graph.c \
     btl_usnic_hwloc.h \
     btl_usnic_mca.c \
     btl_usnic_proc.c \

ompi/mca/btl/usnic/btl_usnic_graph.h

@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) 2014      Cisco Systems, Inc.  All rights reserved.
+ * $COPYRIGHT$
+ *
+ * Additional copyrights may follow
+ *
+ * $HEADER$
+ */
+
+/* Implements an adjacency-list-based weighted directed graph (digraph),
+ * focused on supporting bipartite digraphs and flow-network problems.
+ *
+ * Note that some operations might be more efficient if this structure were
+ * converted to use an adjacency matrix instead of an adjacency list.  OTOH
+ * that complicates other pieces of the implementation (specifically, adding
+ * and removing edges). */
+
+#ifndef BTL_USNIC_GRAPH_H
+#define BTL_USNIC_GRAPH_H
+
+#include "ompi_config.h"
+
+struct ompi_btl_usnic_vertex_t;
+struct ompi_btl_usnic_edge_t;
+struct ompi_btl_usnic_graph_t;
+
+typedef struct ompi_btl_usnic_vertex_t ompi_btl_usnic_vertex_t;
+typedef struct ompi_btl_usnic_edge_t ompi_btl_usnic_edge_t;
+typedef struct ompi_btl_usnic_graph_t ompi_btl_usnic_graph_t;
+
+/**
+ * callback function pointer type for cleaning up user data associated with a
+ * vertex or edge */
+typedef void (*ompi_btl_usnic_cleanup_fn_t)(void *user_data);
+
+/**
+ * create a new empty graph
+ *
+ * Any new vertices will have NULL user data associated.
+ *
+ * @param[in] v_data_cleanup_fn  cleanup function to use for vertex user data
+ * @param[in] e_data_cleanup_fn  cleanup function to use for edge user data
+ * @param[out] g_out             the created graph
+ *
+ * @returns OMPI_SUCCESS or an OMPI error code
+ */
+int ompi_btl_usnic_gr_create(ompi_btl_usnic_cleanup_fn_t v_data_cleanup_fn,
+                             ompi_btl_usnic_cleanup_fn_t e_data_cleanup_fn,
+                             ompi_btl_usnic_graph_t **g_out);
+
+/**
+ * free the given graph
+ *
+ * Any user data associated with vertices or edges in the graph will have
+ * the given edge/vertex cleanup callback invoked in some arbitrary order.
+ *
+ * @returns OMPI_SUCCESS or an OMPI error code
+ */
+int ompi_btl_usnic_gr_free(ompi_btl_usnic_graph_t *g);
+
+/**
+ * clone (deep copy) the given graph
+ *
+ * Note that copy_user_data==true is not currently supported (requires the
+ * addition of a copy callback for user data).
+ *
+ * @param[in] g               the graph to clone
+ * @param[in] copy_user_data  if true, copy vertex/edge user data to the new
+ *                            graph
+ * @param[in] g_clone_out     the resulting cloned graph
+ * @returns OMPI_SUCCESS or an OMPI error code
+ */
+int ompi_btl_usnic_gr_clone(const ompi_btl_usnic_graph_t *g,
+                            bool copy_user_data,
+                            ompi_btl_usnic_graph_t **g_clone_out);
+
+/**
+ * return the number of edges for which this vertex is a destination
+ *
+ * @param[in] g       the graph to query
+ * @param[in] vertex  the vertex id to query
+ * @returns the number of edges for which this vertex is a destination
+ */
+int ompi_btl_usnic_gr_indegree(const ompi_btl_usnic_graph_t *g,
+                               int vertex);
+
+/**
+ * return the number of edges for which this vertex is a source
+ *
+ * @param[in] g       the graph to query
+ * @param[in] vertex  the vertex id to query
+ * @returns the number of edges for which this vertex is a source
+ */
+int ompi_btl_usnic_gr_outdegree(const ompi_btl_usnic_graph_t *g,
+                                int vertex);
+
+/**
+ * add an edge to the given graph
+ *
+ * @param[in] from      source vertex ID
+ * @param[in] to        target vertex ID
+ * @param[in] cost      cost value for this edge (lower is better)
+ * @param[in] capacity  maximum flow transmissible on this edge
+ * @param[in] e_data    caller data to associate with this edge, useful for
+ *                      debugging or minimizing state shared across components
+ *
+ * @returns OMPI_SUCCESS or an OMPI error code
+ */
+int ompi_btl_usnic_gr_add_edge(ompi_btl_usnic_graph_t *g,
+                               int from,
+                               int to,
+                               int64_t cost,
+                               int capacity,
+                               void *e_data);
+
+/**
+ * add a vertex to the given graph
+ *
+ * @param[in]  g          graph to manipulate
+ * @param[in]  v_data     data to associate with the new vertex
+ * @param[out] index_out  integer index of the new vertex.  May be NULL.
+ *
+ * @returns OMPI_SUCCESS or an OMPI error code
+ */
+int ompi_btl_usnic_gr_add_vertex(ompi_btl_usnic_graph_t *g,
+                                 void *v_data,
+                                 int *index_out);
+
+/**
+ * compute the order of a graph (number of vertices)
+ *
+ * @param[in] g the graph to query
+ */
+int ompi_btl_usnic_gr_order(const ompi_btl_usnic_graph_t *g);
+
+/**
+ * This function solves the "assignment problem":
+ * http://en.wikipedia.org/wiki/Assignment_problem
+ *
+ * The goal is to find a maximum cardinality, minimum cost matching in a
+ * weighted bipartite graph.  Maximum cardinality takes priority over minimum
+ * cost.
+ *
+ * Capacities in the given graph are ignored (assumed to be 1 at the start).
+ * It is also assumed that the graph only contains edges from one vertex set
+ * to the other and that no edges exist in the reverse direction ("forward"
+ * edges only).
+ *
+ * The algorithm(s) used will be deterministic.  That is, given the exact same
+ * graph, two calls to this routine will result in the same matching result.
+ *
+ * @param[in] g                     an acyclic bipartite directed graph for
+ *                                  which a matching is sought
+ * @param[out] num_match_edges_out  number edges found in the matching
+ * @param[out] match_edges_out      an array of (u,v) vertex pairs indicating
+ *                                  which edges are in the matching
+ *
+ * @returns OMPI_SUCCESS or an OMPI error code
+ */
+int ompi_btl_usnic_solve_bipartite_assignment(const ompi_btl_usnic_graph_t *g,
+                                              int *num_match_edges_out,
+                                              int **match_edges_out);
+#endif /* BTL_USNIC_GRAPH_H */