Region info transfer struct type and helper functions (#247)

* Fix cache flush (#226)

* Fix a thread race issue that may cause memory error when larger than cache max size data is transferred

* Add a test that writes more data than server cache size

* Fix CI run command

* checkpoint

* Switch variables such as count_0, start_0, and size0... to arrays

This will reduce code duplication, reduce bugs, and make it easier
to switch to support n-dimnesional data.

* clang format

* checkpoint

* created better function names and documentation

* remove

* Committing clang-format changes

* clang format

* remove file

* change for use helper function

* fix bug with incorrect helper function call

---------

Co-authored-by: Houjun Tang <htang4@lbl.gov>
Co-authored-by: github-actions <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Jean Luca Bez <jlbez@lbl.gov>

Author: 4 people

src/api/pdc_client_connect.c

@@ -3047,30 +3047,10 @@ pack_region_metadata(int ndim, uint64_t *offset, uint64_t *size, region_info_tra
 
     FUNC_ENTER(NULL);
     transfer->ndim = ndim;
-    if (ndim >= 1) {
-        transfer->start_0 = offset[0];
-        transfer->count_0 = size[0];
-    }
-    else {
-        transfer->start_0 = 0;
-        transfer->count_0 = 0;
-    }
-    if (ndim >= 2) {
-        transfer->count_1 = size[1];
-        transfer->start_1 = offset[1];
-    }
-    else {
-        transfer->start_1 = 0;
-        transfer->count_1 = 0;
-    }
-    if (ndim >= 3) {
-        transfer->count_2 = size[2];
-        transfer->start_2 = offset[2];
-    }
-    else {
-        transfer->start_2 = 0;
-        transfer->count_2 = 0;
-    }
+
+    PDC_copy_region_desc(offset, transfer->start, ndim, ndim);
+    PDC_copy_region_desc(size, transfer->count, ndim, ndim);
+
     fflush(stdout);
     FUNC_LEAVE(ret_value);
 }
@@ -3521,16 +3501,9 @@ PDC_Client_transfer_request(void *buf, pdcid_t obj_id, uint32_t data_server_id,
     in.access_type = access_type;
     in.remote_unit = unit;
     in.obj_id      = obj_id;
-    in.obj_ndim    = obj_ndim;
-    if (in.obj_ndim >= 1) {
-        in.obj_dim0 = obj_dims[0];
-    }
-    if (in.obj_ndim >= 2) {
-        in.obj_dim1 = obj_dims[1];
-    }
-    if (in.obj_ndim >= 3) {
-        in.obj_dim2 = obj_dims[2];
-    }
+
+    in.obj_ndim = obj_ndim;
+    PDC_copy_region_desc(obj_dims, in.obj_dims, in.obj_ndim, in.obj_ndim);
 
     // Compute metadata server id
     meta_server_id = PDC_get_server_by_obj_id(obj_id, pdc_server_num_g);
@@ -6586,8 +6559,8 @@ PDC_Client_read_with_storage_meta(int nobj, region_storage_meta_t **all_storage_
         prev_fname = fname;
 
         // TODO: currently assumes 1d data and 1 storage region per object
-        storage_start = all_storage_meta[i]->region_transfer.start_0;
-        storage_count = all_storage_meta[i]->region_transfer.count_0;
+        storage_start = all_storage_meta[i]->region_transfer.start[0];
+        storage_count = all_storage_meta[i]->region_transfer.count[0];
         req_start     = storage_start;
         req_count     = storage_count;
         file_offset   = all_storage_meta[i]->offset;

src/api/pdc_region/include/pdc_region.h

@@ -27,10 +27,13 @@
 
 #include "pdc_public.h"
 #include "pdc_obj.h"
+
 #ifdef ENABLE_MPI
 #include "mpi.h"
 #endif
 
+#define DIM_MAX 4
+
 /**************************/
 /* Library Public Struct */
 /**************************/
@@ -46,6 +49,13 @@ struct pdc_region_info {
     size_t                unit;
 };
 
+// Similar structure PDC_region_info_t defined in pdc_obj_pkg.h
+typedef struct region_info_transfer_t {
+    size_t   ndim;
+    uint64_t start[DIM_MAX];
+    uint64_t count[DIM_MAX];
+} region_info_transfer_t;
+
 typedef enum {
     PDC_TRANSFER_STATUS_COMPLETE  = 0,
     PDC_TRANSFER_STATUS_PENDING   = 1,
@@ -253,4 +263,129 @@ perr_t PDCreg_obtain_lock(pdcid_t obj_id, pdcid_t reg_id, pdc_access_t access_ty
  */
 perr_t PDCreg_release_lock(pdcid_t obj_id, pdcid_t reg_id, pdc_access_t access_type);
 
+/**
+ * @brief Check if two region info transfers are identical.
+ *
+ * Compares two region info transfer structures (`reg1` and `reg2`) to determine if they
+ * are equal. The comparison checks if all bytes within the structures match.
+ *
+ * @param reg1 [IN] Pointer to the first region info transfer to compare.
+ * @param reg2 [IN] Pointer to the second region info transfer to compare.
+ *
+ * @return 1 if the region info transfers are identical, -1 otherwise.
+ */
+pbool_t PDC_region_info_transfer_t_is_equal(const region_info_transfer_t *reg1,
+                                            const region_info_transfer_t *reg2);
+
+/**
+ * @brief Copy a region info transfer to another region.
+ *
+ * Copies the data from one region info transfer structure (`src_reg`) to another (`dest_reg`).
+ *
+ * @param src_reg [IN] Pointer to the source region info transfer to copy from.
+ * @param dest_reg [OUT] Pointer to the destination region info transfer to copy to.
+ *
+ * @return Non-negative on success, negative on failure.
+ */
+perr_t PDC_copy_region_info_transfer_t(const region_info_transfer_t *src_reg,
+                                       region_info_transfer_t *      dest_reg);
+
+/**
+ * @brief Calculate the size of a region descriptor in bytes.
+ *
+ * This function computes the size of the region described by `src_reg` in bytes by
+ * multiplying the size of each dimension by the element size (`unit`).
+ * The size in bytes is computed as the product of all dimensions, scaled by `unit`.
+ *
+ * @param src_reg [IN] Pointer to the source region descriptor (in elements)
+ * @param unit [IN] Size of each element in bytes
+ * @param ndim [IN] Number of dimensions in the region descriptor
+ *
+ * @return The size of the region in bytes.
+ */
+uint64_t PDC_get_region_desc_size_bytes(uint64_t *src_reg, int unit, int ndim);
+
+/**
+ * @brief Calculate the size of a region descriptor in elements from region desccriptor in bytes.
+ *
+ * This function computes the size of the region described by `src_reg` in terms of the
+ * number of elements by dividing the given byte size by the element size (`unit`).
+ *
+ * @param src_reg [IN] Pointer to the source region descriptor (in bytes)
+ * @param unit [IN] Size of each element in bytes
+ * @param ndim [IN] Number of dimensions in the region descriptor
+ *
+ * @return The size of the region in terms of the number of elements.
+ */
+uint64_t PDC_get_region_desc_size_from_bytes_to_elements(const uint64_t *src_reg, int unit, int ndim);
+
+/**
+ * @brief Calculate the total size of a region descriptor in elements.
+ *
+ * This function computes the total size of the region described by `src_reg`,
+ * by multiplying the dimensions of the region. The size is returned in terms
+ * of the number of elements, not bytes.
+ *
+ * @param src_reg [IN] Pointer to the source region descriptor (in elements)
+ * @param ndim [IN] Number of dimensions in the region descriptor
+ *
+ * @return The total size of the region in terms of the number of elements.
+ */
+uint64_t PDC_get_region_desc_size(const uint64_t *src_reg, int ndim);
+
+/**
+ * @brief Convert a region descriptor from byte units to element units.
+ *
+ * Copies the region dimensions from the source descriptor to the destination descriptor,
+ * converting each dimension from bytes to elements by dividing by the element size.
+ * For each dimension i:
+ * dest_reg[i] = src_reg[i] / unit
+ *
+ * Both source and destination pointers must be non-null.
+ *
+ * @param src_reg [IN] Pointer to the source region descriptor (in bytes)
+ * @param dest_reg [OUT] Pointer to the destination region descriptor (in elements)
+ * @param unit [IN] Size of each element in bytes
+ * @param ndim [IN] Number of dimensions in the region
+ *
+ * @return Non-negative on success, negative on failure.
+ */
+perr_t PDC_copy_region_desc_bytes_to_elements(const uint64_t *src_reg, uint64_t *dest_reg, int unit,
+                                              int ndim);
+
+/**
+ * @brief Copy a region descriptor from source to destination without unit scaling.
+ *
+ * Copies each dimension from the source region descriptor to the destination region
+ * descriptor without applying any scaling. The number of dimensions may differ between
+ * source and destination, in which case only the common number of dimensions is copied.
+ *
+ * Validates that both source and destination pointers are not NULL.
+ *
+ * @param src_reg [IN] Pointer to the source region descriptor
+ * @param dest_reg [OUT] Pointer to the destination region descriptor
+ * @param src_ndim [IN] Number of dimensions in the source region
+ * @param dest_ndim [IN] Number of dimensions in the destination region
+ *
+ * @return Non-negative on success, negative on failure.
+ */
+perr_t PDC_copy_region_desc(const uint64_t *src_reg, uint64_t *dest_reg, int src_ndim, int dest_ndim);
+
+/**
+ * @brief Copy a region descriptor from element units to byte units.
+ *
+ * Sets each dimension of the destination region descriptor equal to the
+ * corresponding dimension of the source descriptor multiplied by the element size in bytes.
+ * For the i-th dimension: dest_reg[i] = src_reg[i] * unit
+ *
+ * @param src_reg [IN] Pointer to the source region descriptor (in elements)
+ * @param dest_reg [OUT] Pointer to the destination region descriptor (in bytes)
+ * @param unit [IN] Size of each element in bytes
+ * @param dest_ndim [IN] Number of dimensions in the destination region
+ *
+ * @return Non-negative on success, negative on failure.
+ */
+perr_t PDC_copy_region_desc_elements_to_bytes(const uint64_t *src_reg, uint64_t *dest_reg, int unit,
+                                              int dest_ndim);
+
 #endif /* PDC_REGION_H */

src/server/include/pdc_client_server_common.h

@@ -53,7 +53,6 @@ extern struct timeval last_cache_activity_timeval_g;
 #define NA_STRING_INFO_LEN           ADDR_MAX / 2
 #define HOSTNAME_LEN                 ADDR_MAX / 8
 #define TMP_DIR_STRING_LEN           ADDR_MAX / 2
-#define DIM_MAX                      4
 #define TAG_LEN_MAX                  2048
 #define OBJ_NAME_MAX                 TAG_LEN_MAX / 2
 #define PDC_SERVER_ID_INTERVEL       1000000000ull
@@ -198,14 +197,6 @@ typedef struct region_list_t {
     // NOTE: when modified, need to change init and deep_cp routines
 } region_list_t;
 
-// Similar structure PDC_region_info_t defined in pdc_obj_pkg.h
-// TODO: currently only support upto four dimensions
-typedef struct region_info_transfer_t {
-    size_t   ndim;
-    uint64_t start_0, start_1, start_2, start_3;
-    uint64_t count_0, count_1, count_2, count_3;
-} region_info_transfer_t;
-
 typedef struct pdc_metadata_transfer_t {
     int32_t     user_id;
     const char *app_name;
@@ -791,9 +782,7 @@ typedef struct {
     hg_bulk_t              local_bulk_handle;
     region_info_transfer_t remote_region;
     uint64_t               obj_id;
-    uint64_t               obj_dim0;
-    uint64_t               obj_dim1;
-    uint64_t               obj_dim2;
+    uint64_t               obj_dims[DIM_MAX];
     size_t                 remote_unit;
     int32_t                obj_ndim;
     uint32_t               meta_server_id;
@@ -1251,45 +1240,17 @@ hg_proc_region_info_transfer_t(hg_proc_t proc, void *data)
         return ret;
     }
 
-    ret = hg_proc_uint64_t(proc, &struct_data->start_0);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->start_1);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->start_2);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->start_3);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->count_0);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->count_1);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->count_2);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
+    for (int i = 0; i < DIM_MAX; i++) {
+        ret = hg_proc_uint64_t(proc, &(struct_data->start[i]));
+        if (ret != HG_SUCCESS) {
+            return ret;
+        }
     }
-    ret = hg_proc_uint64_t(proc, &struct_data->count_3);
-    if (ret != HG_SUCCESS) {
-
-        return ret;
+    for (int i = 0; i < DIM_MAX; i++) {
+        ret = hg_proc_uint64_t(proc, &(struct_data->count[i]));
+        if (ret != HG_SUCCESS) {
+            return ret;
+        }
     }
 
     return ret;
@@ -2687,17 +2648,11 @@ hg_proc_transfer_request_in_t(hg_proc_t proc, void *data)
     if (ret != HG_SUCCESS) {
         return ret;
     }
-    ret = hg_proc_uint64_t(proc, &struct_data->obj_dim0);
-    if (ret != HG_SUCCESS) {
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->obj_dim1);
-    if (ret != HG_SUCCESS) {
-        return ret;
-    }
-    ret = hg_proc_uint64_t(proc, &struct_data->obj_dim2);
-    if (ret != HG_SUCCESS) {
-        return ret;
+    for (int i = 0; i < DIM_MAX; i++) {
+        ret = hg_proc_uint64_t(proc, &struct_data->obj_dims[i]);
+        if (ret != HG_SUCCESS) {
+            return ret;
+        }
     }
     ret = hg_proc_hg_size_t(proc, &struct_data->remote_unit);
     if (ret != HG_SUCCESS) {

src/server/include/pdc_server_metadata.h

@@ -127,16 +127,6 @@ perr_t PDC_Meta_Server_buf_map(buf_map_in_t *in, region_buf_map_t *new_buf_map_p
  */
 perr_t PDC_Meta_Server_buf_unmap(buf_unmap_in_t *in, hg_handle_t *handle);
 
-/**
- * Check if two regions are identical
- *
- * \param reg1 [IN]             Region to compare
- * \param reg2 [IN]             Region to compare
- *
- * \return 1 if they are the same/-1 otherwise
- */
-pbool_t PDC_region_is_identical(region_info_transfer_t reg1, region_info_transfer_t reg2);
-
 /**
  * Check if two regions overlap
  *