src/class/pmix_bitmap.h

0001 /* -*- Mode: C; c-basic-offset:4 ; -*- */
0002 /*
0003  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2014 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2007      Cisco Systems, Inc.  All rights reserved.
0014  * Copyright (c) 2010-2012 Oak Ridge National Labs.  All rights reserved.
0015  * Copyright (c) 2018-2020 Intel, Inc.  All rights reserved.
0016  * Copyright (c) 2021      Nanook Consulting.  All rights reserved.
0017  * $COPYRIGHT$
0018  *
0019  * Additional copyrights may follow
0020  *
0021  * $HEADER$
0022  *
0023  */
0024
0025 /** @file
0026  *
0027  *  A bitmap implementation. The bits start off with 0, so this bitmap
0028  *  has bits numbered as bit 0, bit 1, bit 2 and so on. This bitmap
0029  *  has auto-expansion capabilities, that is once the size is set
0030  *  during init, it can be automatically expanded by setting the bit
0031  *  beyond the current size. But note, this is allowed just when the
0032  *  bit is set -- so the valid functions are set_bit and
0033  *  find_and_set_bit. Other functions like clear, if passed a bit
0034  *  outside the initialized range will result in an error.
0035  *
0036  *  To allow these bitmaps to track fortran handles (which MPI defines
0037  *  to be Fortran INTEGER), we offer a pmix_bitmap_set_max_size, so that
0038  *  the upper layer can ask to never have more than
0039  *  OMPI_FORTRAN_HANDLE_MAX, which is min(INT_MAX, fortran INTEGER max).
0040  */
0041
0042 #ifndef PMIX_BITMAP_H
0043 #define PMIX_BITMAP_H
0044
0045 #include "src/include/pmix_config.h"
0046
0047 #include <string.h>
0048
0049 #include "src/class/pmix_object.h"
0050
0051 BEGIN_C_DECLS
0052
0053 struct pmix_bitmap_t {
0054     pmix_object_t super; /**< Subclass of pmix_object_t */
0055     uint64_t *bitmap;    /**< The actual bitmap array of characters */
0056     int array_size;      /**< The actual array size that maintains the bitmap */
0057     int max_size;        /**< The maximum size that this bitmap may grow (optional) */
0058 };
0059
0060 typedef struct pmix_bitmap_t pmix_bitmap_t;
0061
0062 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_bitmap_t);
0063
0064 /**
0065  * Set the maximum size of the bitmap.
0066  * May be reset any time, but HAS TO BE SET BEFORE pmix_bitmap_init!
0067  *
0068  * @param  bitmap     The input bitmap (IN)
0069  * @param  max_size   The maximum size of the bitmap in terms of bits (IN)
0070  * @return PMIX error code or success
0071  *
0072  */
0073 PMIX_EXPORT int pmix_bitmap_set_max_size(pmix_bitmap_t *bm, int max_size);
0074
0075 /**
0076  * Initializes the bitmap and sets its size. This must be called
0077  * before the bitmap can be actually used
0078  *
0079  * @param  bitmap The input bitmap (IN)
0080  * @param  size   The initial size of the bitmap in terms of bits (IN)
0081  * @return PMIX error code or success
0082  *
0083  */
0084 PMIX_EXPORT int pmix_bitmap_init(pmix_bitmap_t *bm, int size);
0085
0086 /**
0087  * Set a bit of the bitmap. If the bit asked for is beyond the current
0088  * size of the bitmap, then the bitmap is extended to accommodate the
0089  * bit
0090  *
0091  * @param  bitmap The input bitmap (IN)
0092  * @param  bit    The bit which is to be set (IN)
0093  * @return PMIX error code or success
0094  *
0095  */
0096 PMIX_EXPORT int pmix_bitmap_set_bit(pmix_bitmap_t *bm, int bit);
0097
0098 /**
0099  * Clear/unset a bit of the bitmap. If the bit is beyond the current
0100  * size of the bitmap, an error is returned
0101  *
0102  * @param  bitmap The input bitmap (IN)
0103  * @param  bit    The bit which is to be cleared (IN)
0104  * @return PMIX error code if the bit is out of range, else success
0105  *
0106  */
0107 PMIX_EXPORT int pmix_bitmap_clear_bit(pmix_bitmap_t *bm, int bit);
0108
0109 /**
0110  * Find out if a bit is set in the bitmap
0111  *
0112  * @param  bitmap  The input bitmap (IN)
0113  * @param  bit     The bit which is to be checked (IN)
0114  * @return true    if the bit is set
0115  *         false   if the bit is not set OR the index
0116  *                 is outside the bounds of the provided
0117  *                 bitmap
0118  *
0119  */
0120 PMIX_EXPORT bool pmix_bitmap_is_set_bit(pmix_bitmap_t *bm, int bit);
0121
0122 /**
0123  * Find the first clear bit in the bitmap and set it
0124  *
0125  * @param  bitmap     The input bitmap (IN)
0126  * @param  position   Position of the first clear bit (OUT)
0127
0128  * @return err        PMIX_SUCCESS on success
0129  */
0130 PMIX_EXPORT int pmix_bitmap_find_and_set_first_unset_bit(pmix_bitmap_t *bm, int *position);
0131
0132 /**
0133  * Clear all bits in the bitmap
0134  *
0135  * @param bitmap The input bitmap (IN)
0136  * @return PMIX error code if bm is NULL
0137  *
0138  */
0139 PMIX_EXPORT int pmix_bitmap_clear_all_bits(pmix_bitmap_t *bm);
0140
0141 /**
0142  * Set all bits in the bitmap
0143  * @param bitmap The input bitmap (IN)
0144  * @return PMIX error code if bm is NULL
0145  *
0146  */
0147 PMIX_EXPORT int pmix_bitmap_set_all_bits(pmix_bitmap_t *bm);
0148
0149 /**
0150  * Gives the current size (number of bits) in the bitmap. This is the
0151  * legal (accessible) number of bits
0152  *
0153  * @param bitmap The input bitmap (IN)
0154  * @return PMIX error code if bm is NULL
0155  *
0156  */
0157 static inline int pmix_bitmap_size(pmix_bitmap_t *bm)
0158 {
0159     return (NULL == bm) ? 0 : (bm->array_size * ((int) (sizeof(*bm->bitmap) * 8)));
0160 }
0161
0162 /**
0163  * Copy a bitmap
0164  *
0165  * @param dest Pointer to the destination bitmap
0166  * @param src Pointer to the source bitmap
0167  * @ return PMIX error code if something goes wrong
0168  */
0169 static inline void pmix_bitmap_copy(pmix_bitmap_t *dest, pmix_bitmap_t *src)
0170 {
0171     if (dest->array_size < src->array_size) {
0172         if (NULL != dest->bitmap)
0173             free(dest->bitmap);
0174         dest->max_size = src->max_size;
0175         dest->bitmap = (uint64_t *) malloc(src->array_size * sizeof(uint64_t));
0176     }
0177     memcpy(dest->bitmap, src->bitmap, src->array_size * sizeof(uint64_t));
0178     dest->array_size = src->array_size;
0179 }
0180
0181 /**
0182  * Bitwise AND operator (inplace)
0183  *
0184  * @param dest Pointer to the bitmap that should be modified
0185  * @param right Point to the other bitmap in the operation
0186  * @return PMIX error code if the length of the two bitmaps is not equal or one is NULL.
0187  */
0188 PMIX_EXPORT int pmix_bitmap_bitwise_and_inplace(pmix_bitmap_t *dest, pmix_bitmap_t *right);
0189
0190 /**
0191  * Bitwise OR operator (inplace)
0192  *
0193  * @param dest Pointer to the bitmap that should be modified
0194  * @param right Point to the other bitmap in the operation
0195  * @return PMIX error code if the length of the two bitmaps is not equal or one is NULL.
0196  */
0197 PMIX_EXPORT int pmix_bitmap_bitwise_or_inplace(pmix_bitmap_t *dest, pmix_bitmap_t *right);
0198
0199 /**
0200  * Bitwise XOR operator (inplace)
0201  *
0202  * @param dest Pointer to the bitmap that should be modified
0203  * @param right Point to the other bitmap in the operation
0204  * @return PMIX error code if the length of the two bitmaps is not equal or one is NULL.
0205  */
0206 PMIX_EXPORT int pmix_bitmap_bitwise_xor_inplace(pmix_bitmap_t *dest, pmix_bitmap_t *right);
0207
0208 /**
0209  * If the bitmaps are different
0210  *
0211  * @param left Pointer to a bitmap
0212  * @param right Pointer to another bitmap
0213  * @return true if different, false if the same
0214  */
0215 PMIX_EXPORT bool pmix_bitmap_are_different(pmix_bitmap_t *left, pmix_bitmap_t *right);
0216
0217 /**
0218  * Get a string representation of the bitmap.
0219  * Useful for debugging.
0220  *
0221  * @param bitmap Point to the bitmap to represent
0222  * @return Pointer to the string (caller must free if not NULL)
0223  */
0224 PMIX_EXPORT char *pmix_bitmap_get_string(pmix_bitmap_t *bitmap);
0225
0226 /**
0227  * Return the number of 'unset' bits, up to the specified length
0228  *
0229  * @param bitmap Pointer to the bitmap
0230  * @param len Number of bits to check
0231  * @return Integer
0232  */
0233 PMIX_EXPORT int pmix_bitmap_num_unset_bits(pmix_bitmap_t *bm, int len);
0234
0235 /**
0236  * Return the number of 'set' bits, up to the specified length
0237  *
0238  * @param bitmap Pointer to the bitmap
0239  * @param len Number of bits to check
0240  * @return Integer
0241  */
0242 PMIX_EXPORT int pmix_bitmap_num_set_bits(pmix_bitmap_t *bm, int len);
0243
0244 /**
0245  * Check a bitmap to see if any bit is set
0246  */
0247 PMIX_EXPORT bool pmix_bitmap_is_clear(pmix_bitmap_t *bm);
0248
0249 END_C_DECLS
0250
0251 #endif