/* * Copyright (c) 2004-2005 The Trustees of Indiana University. * All rights reserved. * Copyright (c) 2004-2005 The Trustees of the University of Tennessee. * All rights reserved. * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, * University of Stuttgart. All rights reserved. * Copyright (c) 2004-2005 The Regents of the University of California. * All rights reserved. * $COPYRIGHT$ * * Additional copyrights may follow * * $HEADER$ * */ /** @file * * A bitmap implementation. The bits start off with 0, so this bitmap * has bits numbered as bit 0, bit 1, bit 2 and so on. This bitmap * has auto-expansion capabilities, that is once the size is set * during init, it can be automatically expanded by setting the bit * beyond the current size. But note, this is allowed just when the * bit is set -- so the valid functions are set_bit and * find_and_set_bit. Other functions like clear, if passed a bit * outside the initialized range will result in an error. * * Since these bitmaps are only used to track fortran handles (which * MPI defines to be int's), it is assumed that we can never have more * than OMPI_FORTRAN_HANDLE_MAX (which is min(INT_MAX, fortran * INTEGER max)). * * -------------------------------------------------------------------- * * There are several classes that have forked between their OMPI and * ORTE implementations. As of this writing: * * - ompi_bitmap and orte_bitmap * - ompi_pointer_array and orte_pointer_array * - opal_value_array and orte_value_array * * Short version: * * They were split to accomodate a few differences between * requirements (e.g., "size" parameters being int vs. size_t). It * would be nice to re-merge them someday; there's a few technical * issues that would need to be solved, but nothing impossible. But * there's no pressing *need* to re-merge these, so they have fallen * somewhat low on the priority list of things to do. * * Longer version: * * Although these are generic functionality classes, the ORTE versions * split from the OMPI (soon to be OPAL) versions because of * restrictions imposed by the OMPI versions. Specifically, the OMPI * versions specifically limit size arguments to "int" (in multiple * different ways, e.g.: types of "size" parameters to functions, * maximum allowable values of size parameters, etc.). The ORTE * functions need most size parameters to be of type size_t, not int. * This is the most fundamental difference. In C++, we could have * templated these functions, but we unfortunately can't easily do * that in C (in hindsight, perhaps some preprocessor macros might * have been sufficient, but...). * * Another, more subtle, reason why these were split because of the * scary word "FORTRAN" that appears in some of the upper value limit * checks in the OMPI versions. That is, we always check for max size * against OMPI_FORTRAN_HANDLE_MAX. This value is simply min(INT_MAX, * max value of Fortran INTEGER) -- it's the minimum of the maximum * values of integers in C and Fortran. Usually, it's the same value * (2^32), but the macro is there to ensure that even if it's * different, we end up with a value that can be represented in both * languages. * * This is because the primary purpose of these classes is to serve as * an interface to the Fortran language bindings -- fortran handles * may be directly represented as indices into arrays or bitmaps. * Hence, the size has to be representable in both C and Fortran. * * Regardless, we need to check for *some* max value for the size of * these entites. Perhaps the name "FORTRAN" in the macro is * scary/misleading -- it can certainly be changed in the future if it * would be more clear. So it's ok to have a max -- but perhaps * changing the name would make it more palatable to both layers * (remebering that the max value is still going to be enormous -- * usually 2^32; even if the size is of type size_t, you're going to * run out of memory long before you have 2^32 entries). Or perhaps * the max value can be parameterized to depend on whether the size * type is int or size_t -- I'm sure something can be worked out. * * As mentioned above, if these really are the only two differences * (int vs. size_t and the max sentinel value) -- and I'm pretty sure * that they are -- then these classes can be re-merged someday, * resulting in less code to maintain. This would be good for * long-term maintenance. However, it's kinda low on the priority * list. So it hasn't been done [yet]. If someone wants to do this, * please feel free! :-) * * Given the fact that we just had yet another round of discussions * about the splitting / re-merging of these classes (26 May 2005), it * was decided to put this big comment in the hopes of: * * - someday motivating someone to re-merge the classes * - prevent yet-another round of these discussions by documenting the * issues once and for all :-) */ #ifndef OMPI_BITMAP_H #define OMPI_BITMAP_H #include "ompi_config.h" #include #include "include/types.h" #include "opal/class/opal_object.h" #if defined(c_plusplus) || defined(__cplusplus) extern "C" { #endif struct ompi_bitmap_t { opal_object_t super; /**< Subclass of opal_object_t */ unsigned char *bitmap; /**< The actual bitmap array of characters */ int array_size; /**< The actual array size that maintains the bitmap */ int legal_numbits; /**< The number of bits which are legal (the actual bitmap may contain more bits, since it needs to be rounded to the nearest char */ }; typedef struct ompi_bitmap_t ompi_bitmap_t; OMPI_DECLSPEC OBJ_CLASS_DECLARATION(ompi_bitmap_t); /** * Initializes the bitmap and sets its size. This must be called * before the bitmap can be actually used * * @param bitmap The input bitmap (IN) * @param size The initial size of the bitmap in terms of bits (IN) * @return OMPI error code or success * */ OMPI_DECLSPEC int ompi_bitmap_init (ompi_bitmap_t *bm, int size); /** * Set a bit of the bitmap. If the bit asked for is beyond the current * size of the bitmap, then the bitmap is extended to accomodate the * bit * * @param bitmap The input bitmap (IN) * @param bit The bit which is to be set (IN) * @return OMPI error code or success * */ OMPI_DECLSPEC int ompi_bitmap_set_bit(ompi_bitmap_t *bm, int bit); /** * Clear/unset a bit of the bitmap. If the bit is beyond the current * size of the bitmap, an error is returned * * @param bitmap The input bitmap (IN) * @param bit The bit which is to be cleared (IN) * @return OMPI error code if the bit is out of range, else success * */ OMPI_DECLSPEC int ompi_bitmap_clear_bit(ompi_bitmap_t *bm, int bit); /** * Find out if a bit is set in the bitmap * * @param bitmap The input bitmap (IN) * @param bit The bit which is to be checked (IN) * @return OMPI error code if the bit is out of range * 1 if the bit is set * 0 if the bit is not set * */ OMPI_DECLSPEC int ompi_bitmap_is_set_bit(ompi_bitmap_t *bm, int bit); /** * Find the first clear bit in the bitmap and set it * * @param bitmap The input bitmap (IN) * @param position Position of the first clear bit (OUT) * @return err OMPI_SUCCESS on success */ OMPI_DECLSPEC int ompi_bitmap_find_and_set_first_unset_bit(ompi_bitmap_t *bm, int *position); /** * Clear all bits in the bitmap * * @param bitmap The input bitmap (IN) * @return OMPI error code if bm is NULL * */ OMPI_DECLSPEC int ompi_bitmap_clear_all_bits(ompi_bitmap_t *bm); /** * Set all bits in the bitmap * @param bitmap The input bitmap (IN) * @return OMPI error code if bm is NULL * */ OMPI_DECLSPEC int ompi_bitmap_set_all_bits(ompi_bitmap_t *bm); /** * Gives the current size (number of bits) in the bitmap. This is the * legal (accessible) number of bits * * @param bitmap The input bitmap (IN) * @return OMPI error code if bm is NULL * */ static inline int ompi_bitmap_size(ompi_bitmap_t *bm) { return (NULL == bm) ? 0 : bm->legal_numbits; } #if defined(c_plusplus) || defined(__cplusplus) } #endif #endif