src/class/pmix_value_array.h

0001 /*
0002  * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
0003  *                         University Research and Technology
0004  *                         Corporation.  All rights reserved.
0005  * Copyright (c) 2004-2006 The University of Tennessee and The University
0006  *                         of Tennessee Research Foundation.  All rights
0007  *                         reserved.
0008  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0009  *                         University of Stuttgart.  All rights reserved.
0010  * Copyright (c) 2004-2005 The Regents of the University of California.
0011  *                         All rights reserved.
0012  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0013  * Copyright (c) 2021-2024 Nanook Consulting  All rights reserved.
0014  * $COPYRIGHT$
0015  *
0016  * Additional copyrights may follow
0017  *
0018  * $HEADER$
0019  */
0020
0021 #ifndef PMIX_VALUE_ARRAY_H
0022 #define PMIX_VALUE_ARRAY_H
0023
0024 #include "src/include/pmix_config.h"
0025
0026 #include <string.h>
0027 #ifdef HAVE_STRINGS_H
0028 #    include <strings.h>
0029 #endif /* HAVE_STRINGS_H */
0030
0031 #include "src/class/pmix_object.h"
0032 #if PMIX_ENABLE_DEBUG
0033 #    include "src/util/pmix_output.h"
0034 #endif
0035 #include "pmix_common.h"
0036
0037 BEGIN_C_DECLS
0038
0039 /*
0040  *  @file  Array of elements maintained by value.
0041  */
0042
0043 struct pmix_value_array_t {
0044     pmix_object_t super;
0045     unsigned char *array_items;
0046     size_t array_item_sizeof;
0047     size_t array_size;
0048     size_t array_alloc_size;
0049 };
0050 typedef struct pmix_value_array_t pmix_value_array_t;
0051
0052 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_value_array_t);
0053
0054 #define PMIX_VALUE_ARRAY_STATIC_INIT \
0055 {                                                   \
0056     .super = PMIX_OBJ_STATIC_INIT(pmix_object_t),   \
0057     .array_items = NULL,                            \
0058     .array_item_sizeof = 0,                         \
0059     .array_size = 0,                                \
0060     .array_alloc_size = 0                           \
0061 }
0062
0063 /**
0064  *  Initialize the array to hold items by value. This routine must
0065  *  be called prior to using the array.
0066  *
0067  *  @param   array       The array to initialize (IN).
0068  *  @param   item_size   The sizeof each array element (IN).
0069  *  @return  PMIX error code
0070  *
0071  * Note that there is no corresponding "finalize" function -- use
0072  * OBJ_DESTRUCT (for stack arrays) or OBJ_RELEASE (for heap arrays) to
0073  * delete it.
0074  */
0075
0076 static inline int pmix_value_array_init(pmix_value_array_t *array, size_t item_sizeof)
0077 {
0078     array->array_item_sizeof = item_sizeof;
0079     array->array_alloc_size = 1;
0080     array->array_size = 0;
0081     array->array_items = (unsigned char *) realloc(array->array_items,
0082                                                    item_sizeof * array->array_alloc_size);
0083     return (NULL != array->array_items) ? PMIX_SUCCESS : PMIX_ERR_OUT_OF_RESOURCE;
0084 }
0085
0086 /**
0087  *  Reserve space in the array for new elements, but do not change the size.
0088  *
0089  *  @param   array   The input array (IN).
0090  *  @param   size    The anticipated size of the array (IN).
0091  *  @return  PMIX error code.
0092  */
0093
0094 static inline int pmix_value_array_reserve(pmix_value_array_t *array, size_t size)
0095 {
0096     if (size > array->array_alloc_size) {
0097         array->array_items = (unsigned char *) realloc(array->array_items,
0098                                                        array->array_item_sizeof * size);
0099         if (NULL == array->array_items) {
0100             array->array_size = 0;
0101             array->array_alloc_size = 0;
0102             return PMIX_ERR_OUT_OF_RESOURCE;
0103         }
0104         array->array_alloc_size = size;
0105     }
0106     return PMIX_SUCCESS;
0107 }
0108
0109 /**
0110  *  Retrieves the number of elements in the array.
0111  *
0112  *  @param   array   The input array (IN).
0113  *  @return  The number of elements currently in use.
0114  */
0115
0116 static inline size_t pmix_value_array_get_size(pmix_value_array_t *array)
0117 {
0118     return array->array_size;
0119 }
0120
0121 /**
0122  *  Set the number of elements in the array.
0123  *
0124  *  @param  array   The input array (IN).
0125  *  @param  size    The new array size.
0126  *
0127  *  @return  PMIX error code.
0128  *
0129  *  Note that resizing the array to a smaller size may not change
0130  *  the underlying memory allocated by the array. However, setting
0131  *  the size larger than the current allocation will grow it. In either
0132  *  case, if the routine is successful, pmix_value_array_get_size() will
0133  *  return the new size.
0134  */
0135
0136 PMIX_EXPORT int pmix_value_array_set_size(pmix_value_array_t *array, size_t size);
0137
0138 /**
0139  *  Macro to retrieve an item from the array by value.
0140  *
0141  *  @param  array       The input array (IN).
0142  *  @param  item_type   The C datatype of the array item (IN).
0143  *  @param  item_index  The array index (IN).
0144  *
0145  *  @returns item       The requested item.
0146  *
0147  *  Note that this does not change the size of the array - this macro is
0148  *  strictly for performance - the user assumes the responsibility of
0149  *  ensuring the array index is valid (0 <= item index < array size).
0150  */
0151
0152 #define PMIX_VALUE_ARRAY_GET_ITEM(array, item_type, item_index) \
0153     ((item_type *) ((array)->array_items))[item_index]
0154
0155 /**
0156  *  Retrieve an item from the array by reference.
0157  *
0158  *  @param  array          The input array (IN).
0159  *  @param  item_index     The array index (IN).
0160  *
0161  *  @return ptr Pointer to the requested item.
0162  *
0163  *  Note that if the specified item_index is larger than the current
0164  *  array size, the array is grown to satisfy the request.
0165  */
0166
0167 static inline void *pmix_value_array_get_item(pmix_value_array_t *array, size_t item_index)
0168 {
0169     if (item_index >= array->array_size
0170         && pmix_value_array_set_size(array, item_index + 1) != PMIX_SUCCESS)
0171         return NULL;
0172     return array->array_items + (item_index * array->array_item_sizeof);
0173 }
0174
0175 /**
0176  *  Macro to set an array element by value.
0177  *
0178  *  @param  array       The input array (IN).
0179  *  @param  item_type   The C datatype of the array item (IN).
0180  *  @param  item_index  The array index (IN).
0181  *  @param  item_value  The new value for the specified index (IN).
0182  *
0183  *  Note that this does not change the size of the array - this macro is
0184  *  strictly for performance - the user assumes the responsibility of
0185  *  ensuring the array index is valid (0 <= item index < array size).
0186  *
0187  * It is safe to free the item after returning from this call; it is
0188  * copied into the array by value.
0189  */
0190
0191 #define PMIX_VALUE_ARRAY_SET_ITEM(array, item_type, item_index, item_value) \
0192     (((item_type *) ((array)->array_items))[item_index] = item_value)
0193
0194 /**
0195  *  Set an array element by value.
0196  *
0197  *  @param   array       The input array (IN).
0198  *  @param   item_index  The array index (IN).
0199  *  @param   item_value  A pointer to the item, which is copied into
0200  *                       the array.
0201  *
0202  *  @return  PMIX error code.
0203  *
0204  * It is safe to free the item after returning from this call; it is
0205  * copied into the array by value.
0206  */
0207
0208 static inline int pmix_value_array_set_item(pmix_value_array_t *array, size_t item_index,
0209                                             const void *item)
0210 {
0211     int rc;
0212     if (item_index >= array->array_size
0213         && (rc = pmix_value_array_set_size(array, item_index + 1)) != PMIX_SUCCESS)
0214         return rc;
0215     memcpy(array->array_items + (item_index * array->array_item_sizeof), item,
0216            array->array_item_sizeof);
0217     return PMIX_SUCCESS;
0218 }
0219
0220 /**
0221  *  Appends an item to the end of the array.
0222  *
0223  *  @param   array    The input array (IN).
0224  *  @param   item     A pointer to the item to append, which is copied
0225  *                    into the array.
0226  *
0227  *  @return  PMIX error code
0228  *
0229  * This will grow the array if it is not large enough to contain the
0230  * item.  It is safe to free the item after returning from this call;
0231  * it is copied by value into the array.
0232  */
0233
0234 static inline int pmix_value_array_append_item(pmix_value_array_t *array, const void *item)
0235 {
0236     return pmix_value_array_set_item(array, array->array_size, item);
0237 }
0238
0239 /**
0240  *  Remove a specific item from the array.
0241  *
0242  *  @param   array       The input array (IN).
0243  *  @param   item_index  The index to remove, which must be less than
0244  *                       the current array size (IN).
0245  *
0246  *  @return  PMIX error code.
0247  *
0248  * All elements following this index are shifted down.
0249  */
0250
0251 static inline int pmix_value_array_remove_item(pmix_value_array_t *array, size_t item_index)
0252 {
0253 #if PMIX_ENABLE_DEBUG
0254     if (item_index >= array->array_size) {
0255         pmix_output(0, "pmix_value_array_remove_item: invalid index %lu\n",
0256                     (unsigned long) item_index);
0257         return PMIX_ERR_BAD_PARAM;
0258     }
0259 #endif
0260     memmove(array->array_items + (array->array_item_sizeof * item_index),
0261             array->array_items + (array->array_item_sizeof * (item_index + 1)),
0262             array->array_item_sizeof * (array->array_size - item_index - 1));
0263     array->array_size--;
0264     return PMIX_SUCCESS;
0265 }
0266
0267 /**
0268  * Get the base pointer of the underlying array.
0269  *
0270  * @param array The input array (IN).
0271  * @param array_type The C datatype of the array (IN).
0272  *
0273  * @returns ptr Pointer to the actual array.
0274  *
0275  * This function is helpful when you need to iterate through an
0276  * entire array; simply get the base value of the array and use native
0277  * C to iterate through it manually.  This can have better performance
0278  * than looping over PMIX_VALUE_ARRAY_GET_ITEM() and
0279  * PMIX_VALUE_ARRAY_SET_ITEM() because it will [potentially] reduce the
0280  * number of pointer dereferences.
0281  */
0282
0283 #define PMIX_VALUE_ARRAY_GET_BASE(array, item_type) ((item_type *) ((array)->array_items))
0284
0285 END_C_DECLS
0286
0287 #endif