Skip to content

API Documentation

Jump to bottom
Syed Ibtisam Tauhidi edited this page Apr 24, 2024 · 6 revisions

ParaGrapher Initialization

Initializes the ParaGrapher library. This function must be called before using any other library functions.

int paragrapher_init()

Returns:

  • 0 on success.
  • -1 on failure.

Opening A Graph

Opens a graph of the specified type and name and prepares it for processing.

paragrapher_graph* paragrapher_open_graph(char* name, paragrapher_graph_type type, void** args, int argc)

Parameters:

  • name: The file name or identifier for the graph.
  • type: The type of the graph, as defined by paragrapher_graph_type enum.
  • args: Additional arguments required for opening the graph, specific to the graph type.
  • argc: The number of additional arguments.

Returns:

  • A pointer to a paragrapher_graph structure if successful.
  • NULL if the graph could not be opened due to an invalid type or other errors.

paragrapher_graph_type options:

Option Vertex ID Size (Bytes) Edge Weight Size (Bytes)
PARAGRAPHER_CSX_WG_400_AP 4 -
PARAGRAPHER_CSX_WG_800_AP 8 -
PARAGRAPHER_CSX_WG_404_AP 4 4

Getting or Setting Options

Gets or sets options for an opened graph.

int paragrapher_get_set_options(paragrapher_graph* graph, paragrapher_request_type request_type, void** args, int argc)

Parameters:

  • graph: A pointer to the graph to configure.
  • request_type: The type of request specifying the option to get or set given by paragrapher_request_type enum.
  • args: Arguments for the request.
  • argc: The number of arguments in args.

Returns:

  • 0 on success.
  • A negative integer, on error, with the specific value indicating the type of error.

paragrapher_request_type options:

Option Type (argv[0]) Type (argv[1])
PARAGRAPHER_REQUEST_GET_GRAPH_PATH char[PATH_MAX] -
PARAGRAPHER_REQUEST_GET_VERTICES_COUNT unsigned long -
PARAGRAPHER_REQUEST_GET_EDGES_COUNT unsigned long -
PARAGRAPHER_REQUEST_LIB_USES_OWN_BUFFERS unsigned long -
PARAGRAPHER_REQUEST_LIB_USES_USER_ARRAYS unsigned long -
PARAGRAPHER_REQUEST_SET_BUFFER_SIZE unsigned long -
PARAGRAPHER_REQUEST_GET_BUFFER_SIZE unsigned long -
PARAGRAPHER_REQUEST_SET_MAX_BUFFERS_COUNT unsigned long -
PARAGRAPHER_REQUEST_GET_MAX_BUFFERS_COUNT unsigned long -
PARAGRAPHER_REQUEST_READ_STATUS paragrapher_read_request* unsigned long
PARAGRAPHER_REQUEST_READ_TOTAL_CALLBACKS paragrapher_read_request* unsigned long
PARAGRAPHER_REQUEST_READ_EDGES paragrapher_read_request* unsigned long

Accessing CSX Offsets and Weights

Getting offsets and weights

Obtains the offsets or weights of vertices in a CSX graph, optionally within a specified range.

void* paragrapher_csx_get_offsets(paragrapher_graph* graph, void* offsets, unsigned long start_vertex, unsigned long end_vertex, void** args, int argc)

void* paragrapher_csx_get_vertex_weights(paragrapher_graph* graph, void* weights, unsigned long start_vertex, unsigned long end_vertex, void** args, int argc)

Parameters:

  • graph: A pointer to the graph.
  • offsets, weights: A buffer to store the offsets or weights.
  • start_vertex, end_vertex: The range of vertices to process.
  • args, argc: Additional arguments for the operation.

Returns:

  • A pointer to the buffer containing the offsets if successful.
  • NULL on failure.

Releasing offsets and weights buffers

Releases the memory allocated for arrays obtained for offsets or weights.

void paragrapher_csx_release_offsets_weights_arrays(paragrapher_graph* graph, void* array)

Parameters:

  • graph: A pointer to the graph.
  • array: The array to be released.

Accessing CSX Edges

Callback function

Callback function for handling data received from asynchronous subgraph reading operations in CSX graph formats. When a block of the graph is read, this callback is invoked by the csx_get_subgraph function to handle the received data.

typedef void (*paragrapher_csx_callback)(paragrapher_read_request* request, paragrapher_edge_block* eb, void* offsets, void* edges, void* buffer_id, void* args)

Parameters:

  • request: A pointer to the paragrapher_read_request structure.
  • eb: A pointer to the structure describing the block of edges being processed.
  • offsets: A pointer to an array containing the vertex offsets within the specified block.
  • edges: A pointer to an array containing the edges within the specified block.
  • buffer_id: A pointer to an identifier for the buffer used during the operation.
  • args: A pointer to any user-defined data or parameters that were passed to the original subgraph request.

Asynchronously read subgraph with callback

Initiates an asynchronous operation to extract a subgraph defined by a range of vertices and edges from a CSX-formatted graph.

paragrapher_read_request* csx_get_subgraph(paragrapher_graph* graph, paragrapher_edge_block* eb, void* offsets, void* edges, paragrapher_csx_callback callback, void* callback_args, void** args, int argc)

Parameters:

  • graph: A pointer to the graph structure where the subgraph is to be extracted.
  • eb: A pointer to the paragrapher_edge_block structure that specifies the range of vertices and edges for which the subgraph should be extracted. This includes start and end vertices and edges.
  • offsets: A pointer to an array where the offsets of the vertices will be stored.
  • edges: A pointer to an array where the edges of the subgraph will be stored.
  • callback: The callback function that the library calls to pass blocks of edges to the reader. It must conform to the paragrapher_csx_callback signature.
  • callback_args: A pointer to any user-defined data that should be passed to the callback function.
  • args: Additional reader-specific arguments provided as an array of void pointers.
  • argc: The count of additional arguments provided in args.

Returns:

  • A pointer to a paragrapher_read_request structure if successful.
  • NULL on failure.

Release buffers

Release or clean up the buffers that have been allocated and used to store graph data during an asynchronous read operation.

void csx_release_read_buffers(paragrapher_read_request* request, paragrapher_edge_block* eb, void* offsets, void* edges)

Parameters:

  • request: A pointer to the paragrapher_read_request returned by paragrapher_csx_get_subgraph or another similar function that initiates an asynchronous read operation.
  • eb: A pointer to the paragrapher_edge_block structure indicating the specific range of edges and vertices involved in the request.
  • buffer_id: A pointer to the identifier for the buffer used during the read operation. This identifier is typically provided during the callback execution and is used to manage and release the correct buffer.

Release reader

Release and clean up all resources associated with a paragrapher_read_request.

void csx_release_read_request(paragrapher_read_request* request)

Parameters:

  • request: A pointer to the paragrapher_read_request structure that represents an ongoing or completed read request.

Accessing COO Edges

Accessing a block of edges in COO format.

paragrapher_read_request* coo_get_edges(paragrapher_graph* graph, unsigned long start_row, unsigned long end_row, void* edges, paragrapher_coo_callback callback, void* callback_args, void** args, int argc)

Parameters:

  • graph: A pointer to the graph structure from which edges are to be read. This graph should be formatted in COO (Coordinate List) format.
  • start_row: The starting row index in the edge list from where to begin reading.
  • end_row: The ending row index in the edge list up to which edges should be read. If set to -1UL, it indicates that reading should continue until the end of the edge list.
  • edges: A pointer to an array where the edges between start_row and end_row will be stored.
  • callback: A callback function invoked by the library to handle the edges read from the graph. This function should conform to the paragrapher_coo_callback signature.
  • callback_args: A

pointer to any user-defined data that should be passed to the callback function.

  • args: Additional reader-specific arguments provided as an array of void pointers.
  • argc: The count of additional arguments provided in args.

Returns:

  • Pointer to a paragrapher_read_request if the operation is initiated successfully.
  • NULL on failure.

Release Graph

Releases the resources associated with a graph.

int paragrapher_release_graph(paragrapher_graph* graph, void** args, int argc)

Parameters:

  • graph: A pointer to the graph to be released.
  • args: Additional arguments required for releasing the graph, specific to the graph type.
  • argc: The number of additional arguments.

Returns:

  • 0 on success.
  • -1 on failure.
Clone this wiki locally