src/class/pmix_pointer_array.h

0001 /* -*- Mode: C; c-basic-offset:4 ; -*- */
0002 /*
0003  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2017 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2017      Intel, Inc. All rights reserved.
0014  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0015  * $COPYRIGHT$
0016  *
0017  * Additional copyrights may follow
0018  *
0019  * $HEADER$
0020  */
0021 /** @file
0022  *
0023  * Utility functions to manage fortran <-> c opaque object
0024  * translation.  Note that since MPI defines fortran handles as
0025  * [signed] int's, we use int everywhere in here where you would
0026  * normally expect size_t.  There's some code that makes sure indices
0027  * don't go above FORTRAN_HANDLE_MAX (which is min(INT_MAX, fortran
0028  * INTEGER max)), just to be sure.
0029  */
0030
0031 #ifndef PMIX_POINTER_ARRAY_H
0032 #define PMIX_POINTER_ARRAY_H
0033
0034 #include "src/include/pmix_config.h"
0035
0036 #include "src/class/pmix_object.h"
0037 #include "src/include/pmix_prefetch.h"
0038
0039 BEGIN_C_DECLS
0040
0041 /**
0042  * dynamic pointer array
0043  */
0044 struct pmix_pointer_array_t {
0045     /** base class */
0046     pmix_object_t super;
0047     /** Index of lowest free element.  NOTE: This is only an
0048         optimization to know where to search for the first free slot.
0049         It does \em not necessarily imply indices all above this index
0050         are not taken! */
0051     int lowest_free;
0052     /** number of free elements in the list */
0053     int number_free;
0054     /** size of list, i.e. number of elements in addr */
0055     int size;
0056     /** maximum size of the array */
0057     int max_size;
0058     /** block size for each allocation */
0059     int block_size;
0060     /** pointer to an array of bits to speed up the research for an empty position. */
0061     uint64_t *free_bits;
0062     /** pointer to array of pointers */
0063     void **addr;
0064 };
0065
0066 #define PMIX_POINTER_ARRAY_STATIC_INIT              \
0067 {                                                   \
0068     .super = PMIX_OBJ_STATIC_INIT(pmix_object_t),   \
0069     .lowest_free = 0,                               \
0070     .number_free = 0,                               \
0071     .size = 0,                                      \
0072     .max_size = 0,                                  \
0073     .block_size = 0,                                \
0074     .free_bits = NULL,                              \
0075     .addr = NULL                                    \
0076 }
0077
0078 /**
0079  * Convenience typedef
0080  */
0081 typedef struct pmix_pointer_array_t pmix_pointer_array_t;
0082 /**
0083  * Class declaration
0084  */
0085 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_pointer_array_t);
0086
0087 /**
0088  * Initialize the pointer array with an initial size of initial_allocation.
0089  * Set the maximum size of the array, as well as the size of the allocation
0090  * block for all subsequent growing operations. Remarque: The pointer array
0091  * has to be created bfore calling this function.
0092  *
0093  * @param array Pointer to pointer of an array (IN/OUT)
0094  * @param initial_allocation The number of elements in the initial array (IN)
0095  * @param max_size The maximum size of the array (IN)
0096  * @param block_size The size for all subsequent grows of the array (IN).
0097  *
0098  * @return PMIX_SUCCESS if all initializations were successful. Otherwise,
0099  *  the error indicate what went wrong in the function.
0100  */
0101 PMIX_EXPORT int pmix_pointer_array_init(pmix_pointer_array_t *array, int initial_allocation,
0102                                         int max_size, int block_size);
0103
0104 /**
0105  * Add a pointer to the array (Grow the array, if need be)
0106  *
0107  * @param array Pointer to array (IN)
0108  * @param ptr Pointer value (IN)
0109  *
0110  * @return Index of inserted array element.  Return value of
0111  *  (-1) indicates an error.
0112  */
0113 PMIX_EXPORT int pmix_pointer_array_add(pmix_pointer_array_t *array, void *ptr);
0114
0115 /**
0116  * Set the value of an element in array
0117  *
0118  * @param array Pointer to array (IN)
0119  * @param index Index of element to be reset (IN)
0120  * @param value New value to be set at element index (IN)
0121  *
0122  * @return Error code.  (-1) indicates an error.
0123  */
0124 PMIX_EXPORT int pmix_pointer_array_set_item(pmix_pointer_array_t *array, int index, void *value);
0125
0126 /**
0127  * Get the value of an element in array
0128  *
0129  * @param array          Pointer to array (IN)
0130  * @param element_index  Index of element to be returned (IN)
0131  *
0132  * @return Error code.  NULL indicates an error.
0133  */
0134
0135 static inline void *pmix_pointer_array_get_item(pmix_pointer_array_t *table, int element_index)
0136 {
0137     void *p;
0138
0139     if (PMIX_UNLIKELY(0 > element_index || table->size <= element_index)) {
0140         return NULL;
0141     }
0142     p = table->addr[element_index];
0143     return p;
0144 }
0145
0146 /**
0147  * Get the size of the pointer array
0148  *
0149  * @param array Pointer to array (IN)
0150  *
0151  * @returns size Size of the array
0152  *
0153  * Simple inline function to return the size of the array in order to
0154  * hide the member field from external users.
0155  */
0156 static inline int pmix_pointer_array_get_size(pmix_pointer_array_t *array)
0157 {
0158     return array->size;
0159 }
0160
0161 /**
0162  * Set the size of the pointer array
0163  *
0164  * @param array Pointer to array (IN)
0165  *
0166  * @param size Desired size of the array
0167  *
0168  * Simple function to set the size of the array in order to
0169  * hide the member field from external users.
0170  */
0171 PMIX_EXPORT int pmix_pointer_array_set_size(pmix_pointer_array_t *array, int size);
0172
0173 /**
0174  * Test whether a certain element is already in use. If not yet
0175  * in use, reserve it.
0176  *
0177  * @param array Pointer to array (IN)
0178  * @param index Index of element to be tested (IN)
0179  * @param value New value to be set at element index (IN)
0180  *
0181  * @return true/false True if element could be reserved
0182  *                    False if element could not be reserved (e.g., in use).
0183  *
0184  * In contrary to array_set, this function does not allow to overwrite
0185  * a value, unless the previous value is NULL ( equiv. to free ).
0186  */
0187 PMIX_EXPORT bool pmix_pointer_array_test_and_set_item(pmix_pointer_array_t *table, int index,
0188                                                       void *value);
0189
0190 /**
0191  * Empty the array.
0192  *
0193  * @param array Pointer to array (IN)
0194  *
0195  */
0196 static inline void pmix_pointer_array_remove_all(pmix_pointer_array_t *array)
0197 {
0198     int i;
0199     if (array->number_free == array->size)
0200         return; /* nothing to do here this time (the array is already empty) */
0201
0202     array->lowest_free = 0;
0203     array->number_free = array->size;
0204     for (i = 0; i < array->size; i++) {
0205         array->addr[i] = NULL;
0206     }
0207     for (i = 0; i < (int) ((array->size + 8 * sizeof(uint64_t) - 1) / (8 * sizeof(uint64_t)));
0208          i++) {
0209         array->free_bits[i] = 0;
0210     }
0211 }
0212
0213 END_C_DECLS
0214
0215 #endif /* PMIX_POINTER_ARRAY_H */