Define a C API for data masking (#2630)

Add a C API for data masking.

Closes #2571 

The objective here is to add a C API that will allow us to associated a data mask with a graph.  Basic functions:
* Create a data mask
* Destroy a data mask
* Associated a data mask with a graph
* Disassociated a data mask from a graph
* Discover what data mask is associated with a graph

Current plan is to allow for the creation of a mask by the caller (the python layer for our current use case) and have it passed in.  We may later add support for other techniques.

This PR can be approved independently, but implementation of the API is dependent on #2679

Authors:
  - Chuck Hastings (https://github.com/ChuckHastings)

Approvers:
  - Brad Rees (https://github.com/BradReesWork)
  - Naim (https://github.com/naimnv)

URL: #2630

cpp/include/cugraph_c/graph.h

@@ -26,6 +26,10 @@ typedef struct {
  int32_t align_;
 } cugraph_graph_t;
 
+typedef struct {
+ int32_t align_;
+} cugraph_data_mask_t;
+
 typedef struct {
  bool_t is_symmetric;
  bool_t is_multigraph;
@@ -130,6 +134,91 @@ cugraph_error_code_t cugraph_mg_graph_create(
 // but didn't want to confuse with original cugraph_free_graph
 void cugraph_mg_graph_free(cugraph_graph_t* graph);
 
+/**
+ * @brief Create a data mask
+ *
+ * @param [in] handle Handle for accessing resources
+ * @param [in] vertex_bit_mask Device array containing vertex bit mask
+ * @param [in] edge_bit_mask Device array containing edge bit mask
+ * @param [in] complement If true, a 0 in one of the bit masks implies
+ * the vertex/edge should be included and a 1 should
+ * be excluded. If false a 1 in one of the bit masks
+ * implies the vertex/edge should be included and a 0
+ * should be excluded.
+ * @param [out] mask An opaque pointer to the constructed mask object
+ * @param [out] error Pointer to an error object storing details of any error. Will
+ * be populated if error code is not CUGRAPH_SUCCESS
+ * @return error code
+ */
+cugraph_error_code_t cugraph_data_mask_create(
+ const cugraph_resource_handle_t* handle,
+ const cugraph_type_erased_device_array_view_t* vertex_bit_mask,
+ const cugraph_type_erased_device_array_view_t* edge_bit_mask,
+ bool_t complement,
+ cugraph_data_mask_t** mask,
+ cugraph_error_t** error);
+
+/**
+ * @brief Get the data mask currently associated with a graph
+ *
+ * @param [in] graph The input graph
+ * @param [out] mask Opaque pointer where we should store the
+ * current mask. Will be NULL if there is no mask
+ * currently assigned to the graph.
+ * @param [out] error Pointer to an error object storing details of any error. Will
+ * be populated if error code is not CUGRAPH_SUCCESS
+ * @return error code
+ */
+cugraph_error_code_t cugraph_graph_get_data_mask(cugraph_graph_t* graph,
+ cugraph_data_mask_t** mask,
+ cugraph_error_t** error);
+
+/**
+ * @brief Associate a data mask with a graph
+ *
+ * NOTE: This function will fail if there is already a data mask associated with this graph
+ *
+ * @param [in] graph The input graph
+ * @param [out] mask Opaque pointer of the new data mask
+ * @param [out] error Pointer to an error object storing details of any error. Will
+ * be populated if error code is not CUGRAPH_SUCCESS
+ * @return error code
+ */
+cugraph_error_code_t cugraph_graph_add_data_mask(cugraph_graph_t* graph,
+ cugraph_data_mask_t* mask,
+ cugraph_error_t** error);
+
+/**
+ * @brief Release the data mask currently associated with a graph
+ *
+ * This function will remove the associated of the current data mask
+ * with this graph. The caller will be responsible for destroying the data
+ * mask using graph_data_mask_destroy.
+ *
+ * If this function is not called and the graph is destroyed, the act of destroying
+ * the graph will also destroy the data mask.
+ *
+ * If this function is called on a graph that is not currently associated with
+ * a graph, then the mask will be set to NULL.
+ *
+ * @param [in] graph The input graph
+ * @param [out] mask Opaque pointer where we should store the
+ * current mask.
+ * @param [out] error Pointer to an error object storing details of any error. Will
+ * be populated if error code is not CUGRAPH_SUCCESS
+ * @return error code
+ */
+cugraph_error_code_t cugraph_graph_release_data_mask(cugraph_graph_t* graph,
+ cugraph_data_mask_t** mask,
+ cugraph_error_t** error);
+
+/**
+ * @brief Destroy a data mask
+ *
+ * @param [in] mask A pointer to the data mask to destroy
+ */
+void cugraph_data_mask_destroy(cugraph_data_mask_t* mask);
+
 #ifdef __cplusplus
 }
 #endif