1 /* -*- Mode: C; c-basic-offset:4 ; -*- */
2 /*
3 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2017 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2017 Intel, Inc. All rights reserved.
14 * $COPYRIGHT$
15 *
16 * Additional copyrights may follow
17 *
18 * $HEADER$
19 */
20 /** @file
21 *
22 * Utility functions to manage fortran <-> c opaque object
23 * translation. Note that since MPI defines fortran handles as
24 * [signed] int's, we use int everywhere in here where you would
25 * normally expect size_t. There's some code that makes sure indices
26 * don't go above FORTRAN_HANDLE_MAX (which is min(INT_MAX, fortran
27 * INTEGER max)), just to be sure.
28 */
29
30 #ifndef PMIX_POINTER_ARRAY_H
31 #define PMIX_POINTER_ARRAY_H
32
33 #include "pmix_config.h"
34
35 #include "src/class/pmix_object.h"
36 #include "src/include/prefetch.h"
37
38 BEGIN_C_DECLS
39
40 /**
41 * dynamic pointer array
42 */
43 struct pmix_pointer_array_t {
44 /** base class */
45 pmix_object_t super;
46 /** Index of lowest free element. NOTE: This is only an
47 optimization to know where to search for the first free slot.
48 It does \em not necessarily imply indices all above this index
49 are not taken! */
50 int lowest_free;
51 /** number of free elements in the list */
52 int number_free;
53 /** size of list, i.e. number of elements in addr */
54 int size;
55 /** maximum size of the array */
56 int max_size;
57 /** block size for each allocation */
58 int block_size;
59 /** pointer to an array of bits to speed up the research for an empty position. */
60 uint64_t* free_bits;
61 /** pointer to array of pointers */
62 void **addr;
63 };
64 /**
65 * Convenience typedef
66 */
67 typedef struct pmix_pointer_array_t pmix_pointer_array_t;
68 /**
69 * Class declaration
70 */
71 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_pointer_array_t);
72
73 /**
74 * Initialize the pointer array with an initial size of initial_allocation.
75 * Set the maximum size of the array, as well as the size of the allocation
76 * block for all subsequent growing operations. Remarque: The pointer array
77 * has to be created bfore calling this function.
78 *
79 * @param array Pointer to pointer of an array (IN/OUT)
80 * @param initial_allocation The number of elements in the initial array (IN)
81 * @param max_size The maximum size of the array (IN)
82 * @param block_size The size for all subsequent grows of the array (IN).
83 *
84 * @return PMIX_SUCCESS if all initializations were succesfull. Otherwise,
85 * the error indicate what went wrong in the function.
86 */
87 PMIX_EXPORT int pmix_pointer_array_init(pmix_pointer_array_t* array,
88 int initial_allocation,
89 int max_size, int block_size);
90
91 /**
92 * Add a pointer to the array (Grow the array, if need be)
93 *
94 * @param array Pointer to array (IN)
95 * @param ptr Pointer value (IN)
96 *
97 * @return Index of inserted array element. Return value of
98 * (-1) indicates an error.
99 */
100 PMIX_EXPORT int pmix_pointer_array_add(pmix_pointer_array_t *array, void *ptr);
101
102 /**
103 * Set the value of an element in array
104 *
105 * @param array Pointer to array (IN)
106 * @param index Index of element to be reset (IN)
107 * @param value New value to be set at element index (IN)
108 *
109 * @return Error code. (-1) indicates an error.
110 */
111 PMIX_EXPORT int pmix_pointer_array_set_item(pmix_pointer_array_t *array,
112 int index, void *value);
113
114 /**
115 * Get the value of an element in array
116 *
117 * @param array Pointer to array (IN)
118 * @param element_index Index of element to be returned (IN)
119 *
120 * @return Error code. NULL indicates an error.
121 */
122
123 static inline void *pmix_pointer_array_get_item(pmix_pointer_array_t *table,
124 int element_index)
125 {
126 void *p;
127
128 if( PMIX_UNLIKELY(0 > element_index || table->size <= element_index) ) {
129 return NULL;
130 }
131 p = table->addr[element_index];
132 return p;
133 }
134
135
136 /**
137 * Get the size of the pointer array
138 *
139 * @param array Pointer to array (IN)
140 *
141 * @returns size Size of the array
142 *
143 * Simple inline function to return the size of the array in order to
144 * hide the member field from external users.
145 */
146 static inline int pmix_pointer_array_get_size(pmix_pointer_array_t *array)
147 {
148 return array->size;
149 }
150
151 /**
152 * Set the size of the pointer array
153 *
154 * @param array Pointer to array (IN)
155 *
156 * @param size Desired size of the array
157 *
158 * Simple function to set the size of the array in order to
159 * hide the member field from external users.
160 */
161 PMIX_EXPORT int pmix_pointer_array_set_size(pmix_pointer_array_t *array, int size);
162
163 /**
164 * Test whether a certain element is already in use. If not yet
165 * in use, reserve it.
166 *
167 * @param array Pointer to array (IN)
168 * @param index Index of element to be tested (IN)
169 * @param value New value to be set at element index (IN)
170 *
171 * @return true/false True if element could be reserved
172 * False if element could not be reserved (e.g., in use).
173 *
174 * In contrary to array_set, this function does not allow to overwrite
175 * a value, unless the previous value is NULL ( equiv. to free ).
176 */
177 PMIX_EXPORT bool pmix_pointer_array_test_and_set_item (pmix_pointer_array_t *table,
178 int index,
179 void *value);
180
181 /**
182 * Empty the array.
183 *
184 * @param array Pointer to array (IN)
185 *
186 */
187 static inline void pmix_pointer_array_remove_all(pmix_pointer_array_t *array)
188 {
189 int i;
190 if( array->number_free == array->size )
191 return; /* nothing to do here this time (the array is already empty) */
192
193 array->lowest_free = 0;
194 array->number_free = array->size;
195 for(i = 0; i < array->size; i++) {
196 array->addr[i] = NULL;
197 }
198 for(i = 0; i < (int)((array->size + 8*sizeof(uint64_t) - 1) / (8*sizeof(uint64_t))); i++) {
199 array->free_bits[i] = 0;
200 }
201 }
202
203 END_C_DECLS
204
205 #endif /* PMIX_POINTER_ARRAY_H */