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