OpenMPI  0.1.1
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  */
46  /** base class */
48  /** synchronization object */
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! */
55  /** number of free elements in the list */
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 */
63  /** pointer to array of pointers */
64  void **addr;
65 };
66 /**
67  * Convenience typedef
68  */
70 /**
71  * Class declaration
72  */
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 
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  */
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  */
182  int index,
183  void *value);
184 
185 /**
186  * Empty the array.
187  *
188  * @param array Pointer to array (IN)
189  *
190  */
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 */
int block_size
block size for each allocation
Definition: opal_pointer_array.h:62
dynamic pointer array
Definition: opal_pointer_array.h:45
void ** addr
pointer to array of pointers
Definition: opal_pointer_array.h:64
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
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
Definition: mutex_unix.h:53
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_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
int size
size of list, i.e.
Definition: opal_pointer_array.h:58
#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
#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_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_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
int number_free
number of free elements in the list
Definition: opal_pointer_array.h:56
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_object_t super
base class
Definition: opal_pointer_array.h:47
opal_mutex_t lock
synchronization object
Definition: opal_pointer_array.h:49
Base object.
Definition: opal_object.h:182
static void opal_pointer_array_remove_all(opal_pointer_array_t *array)
Empty the array.
Definition: opal_pointer_array.h:191
int lowest_free
Index of lowest free element.
Definition: opal_pointer_array.h:54
OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_pointer_array_t)
Class declaration.
Mutual exclusion functions.
A simple C-language object-oriented system with single inheritance and ownership-based memory managem...
int max_size
maximum size of the array
Definition: opal_pointer_array.h:60