Define a C API for data masking

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