OpenMPI  0.1.1
opal_bitmap.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-2007 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) 2007 Cisco Systems, Inc. All rights reserved.
14  * Copyright (c) 2010-2012 Oak Ridge National Labs. All rights reserved.
15  * $COPYRIGHT$
16  *
17  * Additional copyrights may follow
18  *
19  * $HEADER$
20  *
21  */
22 
23 /** @file
24  *
25  * A bitmap implementation. The bits start off with 0, so this bitmap
26  * has bits numbered as bit 0, bit 1, bit 2 and so on. This bitmap
27  * has auto-expansion capabilities, that is once the size is set
28  * during init, it can be automatically expanded by setting the bit
29  * beyond the current size. But note, this is allowed just when the
30  * bit is set -- so the valid functions are set_bit and
31  * find_and_set_bit. Other functions like clear, if passed a bit
32  * outside the initialized range will result in an error.
33  *
34  * To allow these bitmaps to track fortran handles (which MPI defines
35  * to be Fortran INTEGER), we offer a opal_bitmap_set_max_size, so that
36  * the upper layer can ask to never have more than
37  * OMPI_FORTRAN_HANDLE_MAX, which is min(INT_MAX, fortran INTEGER max).
38  * Currently the only user of this is ompi/attribute/attribute.c
39  *
40  */
41 
42 #ifndef OPAL_BITMAP_H
43 #define OPAL_BITMAP_H
44 
45 #include "opal_config.h"
46 
47 #include <string.h>
48 
49 #include "opal/class/opal_object.h"
50 
51 BEGIN_C_DECLS
52 
53 struct opal_bitmap_t {
54  opal_object_t super; /**< Subclass of opal_object_t */
55  unsigned char *bitmap; /**< The actual bitmap array of characters */
56  int array_size; /**< The actual array size that maintains the bitmap */
57  int max_size; /**< The maximum size that this bitmap may grow (optional) */
58 };
59 
60 typedef struct opal_bitmap_t opal_bitmap_t;
61 
63 
64 /**
65  * Set the maximum size of the bitmap.
66  * May be reset any time, but HAS TO BE SET BEFORE opal_bitmap_init!
67  *
68  * @param bitmap The input bitmap (IN)
69  * @param max_size The maximum size of the bitmap in terms of bits (IN)
70  * @return OPAL error code or success
71  *
72  */
73 OPAL_DECLSPEC int opal_bitmap_set_max_size (opal_bitmap_t *bm, int max_size);
74 
75 
76 /**
77  * Initializes the bitmap and sets its size. This must be called
78  * before the bitmap can be actually used
79  *
80  * @param bitmap The input bitmap (IN)
81  * @param size The initial size of the bitmap in terms of bits (IN)
82  * @return OPAL error code or success
83  *
84  */
85 OPAL_DECLSPEC int opal_bitmap_init (opal_bitmap_t *bm, int size);
86 
87 
88 /**
89  * Set a bit of the bitmap. If the bit asked for is beyond the current
90  * size of the bitmap, then the bitmap is extended to accomodate the
91  * bit
92  *
93  * @param bitmap The input bitmap (IN)
94  * @param bit The bit which is to be set (IN)
95  * @return OPAL error code or success
96  *
97  */
98 OPAL_DECLSPEC int opal_bitmap_set_bit(opal_bitmap_t *bm, int bit);
99 
100 
101 /**
102  * Clear/unset a bit of the bitmap. If the bit is beyond the current
103  * size of the bitmap, an error is returned
104  *
105  * @param bitmap The input bitmap (IN)
106  * @param bit The bit which is to be cleared (IN)
107  * @return OPAL error code if the bit is out of range, else success
108  *
109  */
110 OPAL_DECLSPEC int opal_bitmap_clear_bit(opal_bitmap_t *bm, int bit);
111 
112 
113 /**
114  * Find out if a bit is set in the bitmap
115  *
116  * @param bitmap The input bitmap (IN)
117  * @param bit The bit which is to be checked (IN)
118  * @return true if the bit is set
119  * false if the bit is not set OR the index
120  * is outside the bounds of the provided
121  * bitmap
122  *
123  */
124 OPAL_DECLSPEC bool opal_bitmap_is_set_bit(opal_bitmap_t *bm, int bit);
125 
126 
127 /**
128  * Find the first clear bit in the bitmap and set it
129  *
130  * @param bitmap The input bitmap (IN)
131  * @param position Position of the first clear bit (OUT)
132 
133  * @return err OPAL_SUCCESS on success
134  */
136  int *position);
137 
138 
139 /**
140  * Clear all bits in the bitmap
141  *
142  * @param bitmap The input bitmap (IN)
143  * @return OPAL error code if bm is NULL
144  *
145  */
146 OPAL_DECLSPEC int opal_bitmap_clear_all_bits(opal_bitmap_t *bm);
147 
148 
149 /**
150  * Set all bits in the bitmap
151  * @param bitmap The input bitmap (IN)
152  * @return OPAL error code if bm is NULL
153  *
154  */
155 OPAL_DECLSPEC int opal_bitmap_set_all_bits(opal_bitmap_t *bm);
156 
157 
158 /**
159  * Gives the current size (number of bits) in the bitmap. This is the
160  * legal (accessible) number of bits
161  *
162  * @param bitmap The input bitmap (IN)
163  * @return OPAL error code if bm is NULL
164  *
165  */
166 static inline int opal_bitmap_size(opal_bitmap_t *bm)
167 {
168  return (NULL == bm) ? 0 : (bm->array_size * ((int) (sizeof(char) * 8)));
169 }
170 
171 
172 /**
173  * Copy a bitmap
174  *
175  * @param dest Pointer to the destination bitmap
176  * @param src Pointer to the source bitmap
177  * @ return OPAL error code if something goes wrong
178  */
179 static inline void opal_bitmap_copy(opal_bitmap_t *dest, opal_bitmap_t *src)
180 {
181  dest->bitmap = (unsigned char*)malloc(src->array_size);
182  memcpy(dest->bitmap, src->bitmap, src->array_size);
183  dest->array_size = src->array_size;
184 }
185 
186 /**
187  * Bitwise AND operator (inplace)
188  *
189  * @param dest Pointer to the bitmap that should be modified
190  * @param right Point to the other bitmap in the operation
191  * @return OPAL error code if the length of the two bitmaps is not equal or one is NULL.
192  */
193 OPAL_DECLSPEC int opal_bitmap_bitwise_and_inplace(opal_bitmap_t *dest, opal_bitmap_t *right);
194 
195 /**
196  * Bitwise OR operator (inplace)
197  *
198  * @param dest Pointer to the bitmap that should be modified
199  * @param right Point to the other bitmap in the operation
200  * @return OPAL error code if the length of the two bitmaps is not equal or one is NULL.
201  */
202 OPAL_DECLSPEC int opal_bitmap_bitwise_or_inplace(opal_bitmap_t *dest, opal_bitmap_t *right);
203 
204 /**
205  * Bitwise XOR operator (inplace)
206  *
207  * @param dest Pointer to the bitmap that should be modified
208  * @param right Point to the other bitmap in the operation
209  * @return OPAL error code if the length of the two bitmaps is not equal or one is NULL.
210  */
211 OPAL_DECLSPEC int opal_bitmap_bitwise_xor_inplace(opal_bitmap_t *dest, opal_bitmap_t *right);
212 
213 /**
214  * If the bitmaps are different
215  *
216  * @param left Pointer to a bitmap
217  * @param right Pointer to another bitmap
218  * @return true if different, false if the same
219  */
220 OPAL_DECLSPEC bool opal_bitmap_are_different(opal_bitmap_t *left, opal_bitmap_t *right);
221 
222 /**
223  * Get a string representation of the bitmap.
224  * Useful for debugging.
225  *
226  * @param bitmap Point to the bitmap to represent
227  * @return Pointer to the string (caller must free if not NULL)
228  */
229 OPAL_DECLSPEC char * opal_bitmap_get_string(opal_bitmap_t *bitmap);
230 
231 /**
232  * Return the number of 'unset' bits, upto the specified length
233  *
234  * @param bitmap Pointer to the bitmap
235  * @param len Number of bits to check
236  * @return Integer
237  */
238 OPAL_DECLSPEC int opal_bitmap_num_unset_bits(opal_bitmap_t *bm, int len);
239 
240 /**
241  * Return the number of 'set' bits, upto the specified length
242  *
243  * @param bitmap Pointer to the bitmap
244  * @param len Number of bits to check
245  * @return Integer
246  */
247 OPAL_DECLSPEC int opal_bitmap_num_set_bits(opal_bitmap_t *bm, int len);
248 
249 END_C_DECLS
250 
251 #endif
OPAL_DECLSPEC int opal_bitmap_set_max_size(opal_bitmap_t *bm, int max_size)
Set the maximum size of the bitmap.
Definition: opal_bitmap.c:58
OPAL_DECLSPEC char * opal_bitmap_get_string(opal_bitmap_t *bitmap)
Get a string representation of the bitmap.
Definition: opal_bitmap.c:375
Definition: opal_bitmap.h:53
OPAL_DECLSPEC bool opal_bitmap_are_different(opal_bitmap_t *left, opal_bitmap_t *right)
If the bitmaps are different.
Definition: opal_bitmap.c:348
OPAL_DECLSPEC int opal_bitmap_num_unset_bits(opal_bitmap_t *bm, int len)
Return the number of 'unset' bits, upto the specified length.
Definition: opal_bitmap.c:416
static void opal_bitmap_copy(opal_bitmap_t *dest, opal_bitmap_t *src)
Copy a bitmap.
Definition: opal_bitmap.h:179
opal_object_t super
Subclass of opal_object_t.
Definition: opal_bitmap.h:54
OPAL_DECLSPEC int opal_bitmap_find_and_set_first_unset_bit(opal_bitmap_t *bm, int *position)
Find the first clear bit in the bitmap and set it.
Definition: opal_bitmap.c:239
OPAL_DECLSPEC int opal_bitmap_set_bit(opal_bitmap_t *bm, int bit)
Set a bit of the bitmap.
Definition: opal_bitmap.c:115
int array_size
The actual array size that maintains the bitmap.
Definition: opal_bitmap.h:56
OPAL_DECLSPEC int opal_bitmap_set_all_bits(opal_bitmap_t *bm)
Set all bits in the bitmap.
Definition: opal_bitmap.c:226
int max_size
The maximum size that this bitmap may grow (optional)
Definition: opal_bitmap.h:57
OPAL_DECLSPEC int opal_bitmap_bitwise_or_inplace(opal_bitmap_t *dest, opal_bitmap_t *right)
Bitwise OR operator (inplace)
Definition: opal_bitmap.c:300
OPAL_DECLSPEC int opal_bitmap_bitwise_and_inplace(opal_bitmap_t *dest, opal_bitmap_t *right)
Bitwise AND operator (inplace)
Definition: opal_bitmap.c:276
Base object.
Definition: opal_object.h:182
OPAL_DECLSPEC int opal_bitmap_init(opal_bitmap_t *bm, int size)
Initializes the bitmap and sets its size.
Definition: opal_bitmap.c:81
OPAL_DECLSPEC int opal_bitmap_clear_all_bits(opal_bitmap_t *bm)
Clear all bits in the bitmap.
Definition: opal_bitmap.c:214
OPAL_DECLSPEC int opal_bitmap_bitwise_xor_inplace(opal_bitmap_t *dest, opal_bitmap_t *right)
Bitwise XOR operator (inplace)
Definition: opal_bitmap.c:324
unsigned char * bitmap
The actual bitmap array of characters.
Definition: opal_bitmap.h:55
OPAL_DECLSPEC int opal_bitmap_num_set_bits(opal_bitmap_t *bm, int len)
Return the number of 'set' bits, upto the specified length.
Definition: opal_bitmap.c:421
static int opal_bitmap_size(opal_bitmap_t *bm)
Gives the current size (number of bits) in the bitmap.
Definition: opal_bitmap.h:166
A simple C-language object-oriented system with single inheritance and ownership-based memory managem...
OPAL_DECLSPEC int opal_bitmap_clear_bit(opal_bitmap_t *bm, int bit)
Clear/unset a bit of the bitmap.
Definition: opal_bitmap.c:169
OPAL_DECLSPEC bool opal_bitmap_is_set_bit(opal_bitmap_t *bm, int bit)
Find out if a bit is set in the bitmap.
Definition: opal_bitmap.c:190
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236