4. Client API

This section documents the main Client API for PDC. It includes the types, core layer functions, properties, containers, objects, and region management functions. Use the links below to quickly navigate to each subsection:

4.1. Data Types

typedef uint64_t pdcid_t

PDC ID.

0 indicates error success otherwise

typedef int perr_t

PDC error.

Negative indicates error success otherwise

typedef pdc_c_var_type_t pdc_var_type_t

PDC variable types.

List of all variable types:

  • PDC_UNKNOWN = 0 : error

  • PDC_SHORT = 1 : short types

  • PDC_INT = 2 : integer types (identical to int32_t)

  • PDC_UINT = 3 : unsigned integer types (identical to uint32_t)

  • PDC_LONG = 4 : long types

  • PDC_INT8 = 5 : 8-bit integer types

  • PDC_UINT8 = 6 : 8-bit unsigned integer types

  • PDC_INT16 = 7 : 16-bit integer types

  • PDC_UINT16 = 8 : 16-bit unsigned integer types

  • PDC_INT32 = 9 : 32-bit integer types, already listed as PDC_INT

  • PDC_UINT32 = 10 : 32-bit unsigned integer types

  • PDC_INT64 = 11 : 64-bit integer types

  • PDC_UINT64 = 12 : 64-bit unsigned integer types

  • PDC_FLOAT = 13 : floating-point types

  • PDC_DOUBLE = 14 : double types

  • PDC_CHAR = 15 : character types

  • PDC_STRING = 16 : string types

  • PDC_BOOLEAN = 17 : boolean types

  • PDC_VOID_PTR = 18 : void pointer type

  • PDC_SIZE_T = 19 : size_t type

  • PDC_BULKI = 20 : BULKI type

  • PDC_BULKI_ENT = 21 : BULKI_ENTITY type

  • PDC_TYPE_COUNT = 22 : number of variable types (must be last)

enum pdc_prop_type_t

Type of a PDC property.

Indicates what the property is used for when creating objects or containers.

Values:

enumerator PDC_CONT_CREATE

Property applies to container creation.

enumerator PDC_OBJ_CREATE

Property applies to object creation.

enum pdc_region_partition_t

Partitioning strategy for PDC regions of an object.

An abstract region of an object can be partitioned in four ways.

The default is PDC_REGION_STATIC.

Values:

enumerator PDC_OBJ_STATIC

Object static partitioning.

Input transfer requests are directly packed with a one-to-one mapping. The target data server is determined at object create/open time.

enumerator PDC_REGION_STATIC

Region static partitioning.

Each region is equally partitioned across all data servers.

enumerator PDC_REGION_DYNAMIC

Region dynamic partitioning.

The metadata server selects the data server dynamically based on current system load to balance region assignments.

enumerator PDC_REGION_LOCAL

Node-local region placement.

The metadata server selects a data server on the same node (or closest) to the client transferring the request.

enum pdc_lifetime_t

Lifetime of a PDC container.

The default is PDC_PERSIST

Values:

enumerator PDC_PERSIST

The container persists beyond the lifetime of the creating process.

enumerator PDC_TRANSIENT

The container exists only for the duration of the creating process and is deleted when the process exits.

enum pdc_consistency_t

Enum defining the consistency model for PDC objects:

Values:

enumerator PDC_CONSISTENCY_POSIX

Synchronous region writes and reads.

Operations are immediately visible to all processes (POSIX semantics)

enumerator PDC_CONSISTENCY_EVENTUAL

Asynchronous updates.

Reads may return stale data until updates propagate (eventual consistency).

enum pdc_prop_name_t

Values:

enumerator PDC_OBJ_NAME
enumerator PDC_CONT_NAME
enumerator PDC_APP_NAME
enumerator PDC_USER_ID
enum pdc_query_op_t

Values:

enumerator PDC_OP_NONE
enumerator PDC_GT
enumerator PDC_LT
enumerator PDC_GTE
enumerator PDC_LTE
enumerator PDC_EQ
enum pdc_query_combine_op_t

Values:

enumerator PDC_QUERY_NONE
enumerator PDC_QUERY_AND
enumerator PDC_QUERY_OR
enum pdc_query_get_op_t

Values:

enumerator PDC_QUERY_GET_NONE
enumerator PDC_QUERY_GET_NHITS
enumerator PDC_QUERY_GET_SEL
enumerator PDC_QUERY_GET_DATA
typedef struct pdcquery_selection_t pdc_selection_t
typedef struct pdc_query_constraint_t pdc_query_constraint_t
typedef struct pdc_query_t pdc_query_t

4.2. PDC Layer

pdcid_t PDCinit(const char *pdc_name)

Initialize the PDC layer.

Parameters:

pdc_name – [IN] Name of the PDC

Returns:

PDC id on success / 0 on failure

perr_t PDCclose(pdcid_t pdcid)

Close the PDC layer.

Parameters:

pdc_id – [IN] ID of the PDC

Returns:

Non-negative on success/Negative on failure

4.3. Properties

pdcid_t PDCprop_create(pdc_prop_type_t type, pdcid_t pdc_id)

Create PDC property.

Parameters:

  • type – [IN] PDC property creation type (enum type), PDC_CONT_CREATE or PDC_OBJ_CREATE

  • id – [IN] ID of the PDC

Returns:

PDC property id on success/Zero on failure

perr_t PDCprop_close(pdcid_t id)

Close property.

Parameters:

id – [IN] ID of the property

Returns:

Non-negative on success/Negative on failure

4.4. Containers

pdcid_t PDCcont_create(const char *cont_name, pdcid_t cont_create_prop)

Create a container.

Parameters:

  • cont_name – [IN] Name of the container

  • cont_create_prop – [IN] ID of container property returned by PDCprop_create(PDC_CONT_CREATE)

Returns:

Container id on success/Zero on failure

pdcid_t PDCcont_create_col(const char *cont_name, pdcid_t cont_prop_id)

Create a container, used when all ranks are trying to create the same container.

Parameters:

  • cont_name – [IN] Name of the container

  • cont_prop_id – [IN] ID of container property returned by PDCprop_create(PDC_CONT_CREATE)

Returns:

Container id on success/Zero on failure

pdcid_t PDCcont_open(const char *cont_name, pdcid_t pdc_id)

Open a container.

Parameters:

  • cont_name – [IN] Name of the container

  • pdc_id – [IN] ID of pdc

Returns:

Container id on success/Zero on failure

pdcid_t PDCcont_open_col(const char *cont_name, pdcid_t pdc_id)

Open a container collectively.

Parameters:

  • cont_name – [IN] Name of the container

  • pdc_id – [IN] ID of pdc

Returns:

Container id on success/Zero on failure

perr_t PDCcont_close(pdcid_t cont_id)

Close a container.

Parameters:

cont_id – [IN] Container id, returned by PDCcont_open(pdcid_t pdc_id, const char *cont_name)

Returns:

Non-negative on success/Negative on failure

perr_t PDCcont_persist(pdcid_t cont_id)

Persist a transient container.

Parameters:

cont_id – [IN] ID of the container, returned by PDCcont_open(pdcid_t pdc_id, const char *cont_name)

Returns:

Non-negative on success/Negative on failure

4.4. Objects

pdcid_t PDCobj_create(pdcid_t cont_id, const char *obj_name, pdcid_t obj_create_prop)

Create an object.

Parameters:

  • cont_id – [IN] ID of the container

  • obj_name – [IN] Name of the object

  • obj_create_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

Returns:

Object id on success/Zero on failure

pdcid_t PDCobj_create_mpi(pdcid_t cont_id, const char *obj_name, pdcid_t obj_create_prop, int rank_id, MPI_Comm comm)

Create an object.

Parameters:

  • cont_id – [IN] ID of the container

  • obj_name – [IN] Name of the object

  • obj_create_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • rank_id – [IN] MPI process rank

Returns:

Object ID on success/Zero on failure

pdcid_t PDCobj_open(const char *obj_name, pdcid_t pdc_id)

Open an object within a container.

Parameters:

  • pdc_id – [IN] ID of pdc

  • obj_name – [IN] Name of the object

Returns:

Object id on success/Zero on failure

pdcid_t PDCobj_open_col(const char *obj_name, pdcid_t pdc_id)

Open an object within a container collectively.

Parameters:

  • pdc_id – [IN] ID of pdc

  • obj_name – [IN] Name of the object

Returns:

Object id on success/Zero on failure

perr_t PDCobj_close(pdcid_t obj_id)

Close an object.

Parameters:

obj_id – [IN] ID of the object

Returns:

Non-negative on success/Negative on failure

struct pdc_obj_info *PDCobj_get_info(pdcid_t obj_id)

Get object information.

Parameters:

obj_name – [IN] Name of the object

Returns:

Pointer to pdc_obj_info struct on success/Null on failure

pdcid_t PDCprop_obj_dup(pdcid_t prop_id)

Quickly create object property from an existing object property Share the same property with the existing one other than data_loc, data type, buf, which are data related.

Parameters:

  • type – [IN] PDC property creation type (enum type), PDC_CONT_CREATE or PDC_OBJ_CREATE

  • id – [IN] ID of the PDC

Returns:

PDC property id on success/Zero on failure

perr_t PDCprop_set_obj_type(pdcid_t obj_prop, pdc_var_type_t type)

Set object type.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • type – [IN] Object variable type (enum type), i.e. PDC_int_t, PDC_float_t

Returns:

Non-negative on success/Negative on failure

perr_t PDCprop_set_obj_dims(pdcid_t obj_prop, PDC_int_t ndim, uint64_t *dims)

Set object dimension.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • ndim – [IN] Number of dimensions, must be greater than 0

  • dims – [IN] Size of each dimension, positive value, can be PDC_SIZE_UNLIMITED

Returns:

Non-negative on success/Negative on failure

perr_t PDCprop_set_obj_user_id(pdcid_t obj_prop, uint32_t user_id)

Set object user ID.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • user_id – [IN] User id

Returns:

Non-negative on success/Negative on failure

perr_t PDCprop_set_obj_time_step(pdcid_t obj_prop, uint32_t time_step)

Set object time step.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • time_step – [IN] Time step

Returns:

Non-negative on success/Negative on failure

perr_t PDCprop_set_obj_app_name(pdcid_t obj_prop, char *app_name)

Set object application name.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • app_name – [IN] Application name

Returns:

Non-negative on success/Negative on failure

perr_t PDCprop_set_obj_tags(pdcid_t obj_prop, char *tags)

Set object tag.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • tags – [IN] Tags

Returns:

Non-negative on success/Negative on failure

perr_t PDCprop_set_obj_transfer_region_type(pdcid_t obj_prop, pdc_region_partition_t region_partition)

Set object transfer partitioning.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • type – [IN] Object transfer partitioning method (enum type), i.e. PDC_OBJ_STATIC, PDC_REGION_STATIC, PDC_REGION_DYNAMIC

Returns:

Non-negative on success/Negative on failure

obj_handle *PDCobj_iter_start(pdcid_t cont_id)

Iterate over objects in a container.

Parameters:

cont_id – [IN] Container ID, returned by PDCobj_open(pdcid_t pdc_id, const char *cont_name)

Returns:

A pointer to object handle struct on success/NULL on failure

pbool_t PDCobj_iter_null(obj_handle *ohandle)

Check if object handle is pointing to NULL.

Parameters:

ohandle – [IN] A obj_handle struct, returned by PDCobj_iter_start(pdcid_t cont_id)

Returns:

1 on success/0 on failure

struct pdc_obj_info *PDCobj_iter_get_info(obj_handle *ohandle)

Get object information.

Parameters:

ohandle – [IN] A pointer to obj_handle struct, returned by PDCobj_iter_start(pdcid_t cont_id)

Returns:

Pointer to a pdc_obj_info struct on success/NULL on failure

obj_handle *PDCobj_iter_next(obj_handle *ohandle, pdcid_t cont_id)

Iterate the next object.

Parameters:
Returns:

A pointer to object handle struct on success/Zero on failure

4.6. Object Tags

perr_t PDCprop_set_obj_tags(pdcid_t obj_prop, char *tags)

Set object tag.

Parameters:

  • obj_prop – [IN] ID of object property, returned by PDCprop_create(PDC_OBJ_CREATE)

  • tags – [IN] Tags

Returns:

Non-negative on success/Negative on failure

perr_t PDCobj_put_tag(pdcid_t obj_id, char *tag_name, void *tag_value, pdc_var_type_t value_type, psize_t value_size)

Add a tag to an object.

Parameters:

  • obj_id – [IN] Object ID

  • tag_name – [IN] Metadta field name

  • tag_value – [IN] Metadta field value

  • value_size – [IN] ******

Returns:

Non-negative on success/Negative on failure

perr_t PDCobj_get_tag(pdcid_t obj_id, char *tag_name, void **tag_value, pdc_var_type_t *value_type, psize_t *value_size)

Get tag information.

Parameters:

  • obj_id – [IN] Object ID

  • tag_name – [IN] Metadta field name

  • tag_value – [IN] Metadta field value

  • value_size – [IN] ******

Returns:

Non-negative on success/Negative on failure

4.7. Regions

pdcid_t PDCregion_create(psize_t ndims, uint64_t *offset, uint64_t *size)

Create a region.

Parameters:

  • ndims – [IN] Number of dimensions

  • offset – [IN] Offset of each dimension

  • size – [IN] Size of each dimension

Returns:

Object id on success/Zero on failure

perr_t PDCregion_close(pdcid_t region_id)

Close a region.

Parameters:

region_id – [IN] ID of the object

Returns:

Non-negative on success/Negative on failure

4.8. Object Data Transfers

perr_t PDCregion_transfer_start(pdcid_t transfer_request_id)

Start a region transfer from local region to remote region for an object on buf.

Parameters:

transfer_request_id – [IN] ID of the region transfer request

Returns:

Non-negative on success/Negative on failure

perr_t PDCregion_transfer_wait(pdcid_t transfer_request_id)

Block and wait for a region transfer request to finish.

Parameters:

transfer_request_id – [IN] ID of the region transfer request

Returns:

Non-negative on success/Negative on failure

perr_t PDCregion_transfer_close(pdcid_t transfer_request_id)

Close a transfer request, free internal resources.

Parameters:

transfer_request_id – [IN] ID of the region transfer request

Returns:

Non-negative on success/Negative on failure

perr_t PDCregion_transfer_start_all(pdcid_t *transfer_request_id, int size)

Start several region transfer requests (asynchronously), can be for different objects.

Parameters:

  • transfer_request_id – [IN] ID pointer array of the region transfer requests

  • size – [IN] Number of requests in transfer_request_id

Returns:

Non-negative on success/Negative on failure

perr_t PDCregion_transfer_wait_all(pdcid_t *transfer_request_id, int size)

Block and wait for several region transfer requests to finish.

Parameters:

  • transfer_request_id – [IN] ID of the region transfer request

  • size – [IN] Number of requests in transfer_request_id

Returns:

Non-negative on success/Negative on failure

pdcid_t PDCobj_put_data(const char *obj_name, void *data, uint64_t size, pdcid_t cont_id)
Parameters:

  • obj_name – [IN] Object name

  • data – [IN] *********

  • size – [IN] *********

  • n_res – [IN] *********

  • cont_id – [IN] *********

Returns:

Non-negative on success/Negative on failure

perr_t PDCobj_get_data(pdcid_t obj_id, void *data, uint64_t size)
Parameters:

  • obj_id – [IN] Object ID

  • data – [IN] *********

  • size – [IN] *********

Returns:

Non-negative on success/Negative on failure

4.9 Object Data Querying

pdc_query_t *PDCquery_create(pdcid_t obj_id, pdc_query_op_t op, pdc_var_type_t type, void *value)

Create a PDC query.

Parameters:

  • obj_id – [IN] *********

  • op – [IN] *********

  • type – [OUT] *********

  • value – [OUT] *********

Returns:

*******

pdc_query_t *PDCquery_and(pdc_query_t *query1, pdc_query_t *query2)
Parameters:

  • query1 – [IN] *********

  • query2 – [IN] *********

Returns:

******

pdc_query_t *PDCquery_or(pdc_query_t *query1, pdc_query_t *query2)
Parameters:

  • query1 – [IN] *********

  • query2 – [IN] *********

Returns:

******

perr_t PDCquery_sel_region(pdc_query_t *query, struct pdc_region_info *obj_region)
Parameters:

  • query – [IN] *********

  • obj_region – [IN] Object region information

Returns:

Non-negative on success/Negative on failure

perr_t PDCquery_get_selection(pdc_query_t *query, pdc_selection_t *sel)
Parameters:

  • query – [IN] *********

  • sel – [IN] *********

Returns:

Non-negative on success/Negative on failure

perr_t PDCquery_get_data(pdcid_t obj_id, pdc_selection_t *sel, void *obj_data)
Parameters:

  • obj_id – [IN] Object ID

  • sel – [IN] *********

  • obj_data – [IN] ********

Returns:

Non-negative on success/Negative on failure

perr_t PDCquery_get_histogram(pdcid_t obj_id)
Parameters:

obj_id – [IN] Object ID

Returns:

Non-negative on success/Negative on failure

void PDCselection_free(pdc_selection_t *sel)
Parameters:

sel – [IN] *********

void PDCquery_free(pdc_query_t *query)
Parameters:

query – [IN] *********

void PDCquery_free_all(pdc_query_t *query)
Parameters:

query – [IN] *********

void PDCquery_print(pdc_query_t *query)
Parameters:

query – [IN] *********

void PDCselection_print(pdc_selection_t *sel)
Parameters:

sel – [IN] *********

void PDCselection_print_all(pdc_selection_t *sel)
Parameters:

sel – [IN] *********