OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

opal_pointer_array.h
Go to the documentation of this file.
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-2008 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 * See opal_bitmap.h for an explanation of why there is a split
22 * between OPAL and ORTE for this generic class.
23 *
24 * Utility functions to manage fortran <-> c opaque object
25 * translation. Note that since MPI defines fortran handles as
26 * [signed] int's, we use int everywhere in here where you would
27 * normally expect size_t. There's some code that makes sure indices
28 * don't go above FORTRAN_HANDLE_MAX (which is min(INT_MAX, fortran
29 * INTEGER max)), just to be sure.
30 */
31
32 #ifndef OPAL_POINTER_ARRAY_H
33 #define OPAL_POINTER_ARRAY_H
34
35 #include "opal_config.h"
36
37 #include "opal/threads/mutex.h"
38 #include "opal/class/opal_object.h"
39
40 BEGIN_C_DECLS
41
42 /**
43 * dynamic pointer array
44 */
45 struct opal_pointer_array_t {
46 /** base class */
47 opal_object_t super;
48 /** synchronization object */
49 opal_mutex_t lock;
50 /** Index of lowest free element. NOTE: This is only an
51 optimization to know where to search for the first free slot.
52 It does \em not necessarily imply indices all above this index
53 are not taken! */
54 int lowest_free;
55 /** number of free elements in the list */
56 int number_free;
57 /** size of list, i.e. number of elements in addr */
58 int size;
59 /** maximum size of the array */
60 int max_size;
61 /** block size for each allocation */
62 int block_size;
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( 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 OPAL_THREAD_UNLOCK(&array->lock);
204 }
205
206 END_C_DECLS
207
208 #endif /* OPAL_POINTER_ARRAY_H */
opal_pointer_array_t::block_size
int block_size
block size for each allocation
Definition: opal_pointer_array.h:62
opal_pointer_array_t
dynamic pointer array
Definition: opal_pointer_array.h:45
opal_pointer_array_t::addr
void ** addr
pointer to array of pointers
Definition: opal_pointer_array.h:64
opal_pointer_array_set_size
OPAL_DECLSPEC int opal_pointer_array_set_size(opal_pointer_array_t *array, int size)
Set the size of the pointer array.
Definition: opal_pointer_array.c:295
opal_pointer_array_get_size
static int opal_pointer_array_get_size(opal_pointer_array_t *array)
Get the size of the pointer array.
Definition: opal_pointer_array.h:150
opal_mutex_t
Definition: mutex_unix.h:53
opal_pointer_array_get_item
static void * opal_pointer_array_get_item(opal_pointer_array_t *table, int element_index)
Get the value of an element in array.
Definition: opal_pointer_array.h:125
opal_pointer_array_init
OPAL_DECLSPEC int opal_pointer_array_init(opal_pointer_array_t *array, int initial_allocation, int max_size, int block_size)
Initialize the pointer array with an initial size of initial_allocation.
Definition: opal_pointer_array.c:73
opal_pointer_array_t::size
int size
size of list, i.e.
Definition: opal_pointer_array.h:58
OPAL_THREAD_LOCK
#define OPAL_THREAD_LOCK(mutex)
Lock a mutex if opal_using_threads() says that multiple threads may be active in the process...
Definition: mutex.h:223
OPAL_THREAD_UNLOCK
#define OPAL_THREAD_UNLOCK(mutex)
Unlock a mutex if opal_using_threads() says that multiple threads may be active in the process...
Definition: mutex.h:309
opal_pointer_array_set_item
OPAL_DECLSPEC int opal_pointer_array_set_item(opal_pointer_array_t *array, int index, void *value)
Set the value of an element in array.
Definition: opal_pointer_array.c:164
opal_pointer_array_test_and_set_item
OPAL_DECLSPEC bool opal_pointer_array_test_and_set_item(opal_pointer_array_t *table, int index, void *value)
Test whether a certain element is already in use.
Definition: opal_pointer_array.c:233
opal_pointer_array_t::number_free
int number_free
number of free elements in the list
Definition: opal_pointer_array.h:56
opal_pointer_array_add
OPAL_DECLSPEC int opal_pointer_array_add(opal_pointer_array_t *array, void *ptr)
Add a pointer to the array (Grow the array, if need be)
Definition: opal_pointer_array.c:109
opal_pointer_array_t::super
opal_object_t super
base class
Definition: opal_pointer_array.h:47
opal_pointer_array_t::lock
opal_mutex_t lock
synchronization object
Definition: opal_pointer_array.h:49
opal_object_t
Base object.
Definition: opal_object.h:182
opal_pointer_array_remove_all
static void opal_pointer_array_remove_all(opal_pointer_array_t *array)
Empty the array.
Definition: opal_pointer_array.h:191
opal_pointer_array_t::lowest_free
int lowest_free
Index of lowest free element.
Definition: opal_pointer_array.h:54
OBJ_CLASS_DECLARATION
OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_pointer_array_t)
Class declaration.
mutex.h
Mutual exclusion functions.
opal_object.h
A simple C-language object-oriented system with single inheritance and ownership-based memory managem...
opal_pointer_array_t::max_size
int max_size
maximum size of the array
Definition: opal_pointer_array.h:60