lib/silcutil/silcbitops.h

   1 /*
   2
   3   silcbitops.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 - 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/Bit Operations Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Bit operations interface.  The interface can be used to set, clear and
  25  * find bits in an arbitrarily large bitmap.  The interface does not support
  26  * setting the bits atomically.
  27  *
  28  * EXAMPLE
  29  *
  30  * Example with a pre-allocated bitmap:
  31  *
  32  * // Declare bitmap of size of 500 bits
  33  * SILC_BITMAP_DECLARE(bitmap, 500);
  34  * int bitmap_size = SILC_BITMAP_SIZE(500);
  35  *
  36  * // Set 0 bit
  37  * silc_bit_set(bitmap, bitmap_size, 0);
  38  *
  39  * // Set bit number 100
  40  * silc_bit_set(bitmap, bitmap_size, 100);
  41  *
  42  * // Find first set bit from the bitmap
  43  * bit = silc_bit_ffs(bitmap, bitmap_size);
  44  *
  45  * // Find next set bit from the bitmap
  46  * bit = silc_bit_fns(bitmap, bitmap_size, bit + 1);
  47  *
  48  * // Clear bit number 100
  49  * silc_bit_set(bitmap, bitmap_size, 100);
  50  *
  51  ***/
  52
  53 #ifndef SILCBITOPS_H
  54 #define SILCBITOPS_H
  55
  56 #define SILC_BIT_SIZE (SILC_SIZEOF_LONG * 8)
  57
  58 /****d* silcutil/SILC_BITMAP_DECLARE
  59  *
  60  * NAME
  61  *
  62  *    #define SILC_BITMAP_DECLARE(name, bits)
  63  *
  64  * DESCRIPTION
  65  *
  66  *    Macro that can be used to declare a pre-allocated bitmap named `name' of
  67  *    size of `bits' many bits.
  68  *
  69  ***/
  70 #define SILC_BITMAP_DECLARE(name, bits)         \
  71   unsigned long name[SILC_BITMAP_SIZE(bits)]
  72
  73 /****d* silcutil/SILC_BITMAP_SIZE
  74  *
  75  * NAME
  76  *
  77  *    #define SILC_BITMAP_SIZE(bits)
  78  *
  79  * DESCRIPTION
  80  *
  81  *    Macro that returns the size of a bitmap array of size of `bits' many
  82  *    bits.  The returned size can be given as argument to the SILC Bit
  83  *    Operations API functions.
  84  *
  85  ***/
  86 #define SILC_BITMAP_SIZE(bits) (((bits) + SILC_BIT_SIZE) / SILC_BIT_SIZE)
  87
  88 /****f* silcutil/silc_bit_set
  89  *
  90  * SYNOPSIS
  91  *
  92  *    SilcBool silc_bit_set(volatile unsigned long *bitmap,
  93  *                          SilcUInt32 bitmap_size, SilcUInt32 bit);
  94  *
  95  * DESCRIPTION
  96  *
  97  *    Set bit number `bit' in the `bitmap' of size of `bitmap_size'.  Returns
  98  *    FALSE on error and sets silc_errno.
  99  *
 100  ***/
 101 SilcBool silc_bit_set(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 102                       SilcUInt32 bit);
 103
 104 /****f* silcutil/silc_bit_clear
 105  *
 106  * SYNOPSIS
 107  *
 108  *    SilcBool silc_bit_clear(volatile unsigned long *bitmap,
 109  *                           SilcUInt32 bitmap_size,  SilcUInt32 bit);
 110  *
 111  * DESCRIPTION
 112  *
 113  *    Clear bit number `bit' in the `bitmap' of size of `bitmap_size'.
 114  *    Returns FALSE on error and sets silc_errno.
 115  *
 116  ***/
 117 SilcBool silc_bit_clear(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 118                         SilcUInt32 bit);
 119
 120 /****f* silcutil/silc_bit_toggle
 121  *
 122  * SYNOPSIS
 123  *
 124  *    SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
 125  *                             SilcUInt32 bitmap_size, SilcUInt32 bit);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Toggle bit number `bit' in the `bitmap' of size of `bitmap_size'.
 130  *    Returns FALSE on error and sets silc_errno.
 131  *
 132  ***/
 133 SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
 134                          SilcUInt32 bitmap_size, SilcUInt32 bit);
 135
 136 /****f* silcutil/silc_bit_test_and_set
 137  *
 138  * SYNOPSIS
 139  *
 140  *    int silc_bit_test_and_set(volatile unsigned long *bitmap,
 141  *                              SilcUInt32 bitmap_size, SilcUInt32 bit);
 142  *
 143  * DESCRIPTION
 144  *
 145  *    Set bit number `bit' in the `bitmap' of size of `bitmap_size' and
 146  *    return the value before setting.  Returns -1 on error and sets
 147  *    silc_errno.
 148  *
 149  ***/
 150 int silc_bit_test_and_set(volatile unsigned long *bitmap,
 151                           SilcUInt32 bitmap_size, SilcUInt32 bit);
 152
 153 /****f* silcutil/silc_bit_test_and_clear
 154  *
 155  * SYNOPSIS
 156  *
 157  *    int silc_bit_test_and_clear(volatile unsigned long *bitmap,
 158  *                               SilcUInt32 bitmap_size,  SilcUInt32 bit);
 159  *
 160  * DESCRIPTION
 161  *
 162  *    Clear bit number `bit' in the `bitmap' of size of `bitmap_size' and
 163  *    return the value before setting.  Returns -1 on error and sets
 164  *    silc_errno.
 165  *
 166  ***/
 167 int silc_bit_test_and_clear(volatile unsigned long *bitmap,
 168                             SilcUInt32 bitmap_size, SilcUInt32 bit);
 169
 170 /****f* silcutil/silc_bit_test_and_toggle
 171  *
 172  * SYNOPSIS
 173  *
 174  *    int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
 175  *                                 SilcUInt32 bitmap_size, SilcUInt32 bit);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Toggle bit number `bit' in the `bitmap' of size of `bitmap_size' and
 180  *    return the value before setting.  Returns -1 on error and sets
 181  *    silc_errno.
 182  *
 183  ***/
 184 int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
 185                              SilcUInt32 bitmap_size, SilcUInt32 bit);
 186
 187 /****f* silcutil/silc_bit_get
 188  *
 189  * SYNOPSIS
 190  *
 191  *    int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 192  *                     SilcUInt32 bit);
 193  *
 194  * DESCRIPTION
 195  *
 196  *    Returns the value of the bit number `bit' or -1 on error and sets
 197  *    silc_errno.
 198  *
 199  ***/
 200 int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 201                  SilcUInt32 bit);
 202
 203 /****f* silcutil/silc_bit_ffs
 204  *
 205  * SYNOPSIS
 206  *
 207  *    int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 208  *
 209  * DESCRIPTION
 210  *
 211  *    Returns the bit number of the first set bit in the `bitmap' of size
 212  *    of `bitmap_size'.  Returns -1 on error or when there were no set bits
 213  *    and sets silc_errno.
 214  *
 215  ***/
 216 int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 217
 218 /****f* silcutil/silc_bit_ffz
 219  *
 220  * SYNOPSIS
 221  *
 222  *    int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 223  *
 224  * DESCRIPTION
 225  *
 226  *    Returns the bit number of the first zero bit in the `bitmap' of size
 227  *    of `bitmap_size'.  Returns -1 on error or when there were no zero bits
 228  *    and sets silc_errno.
 229  *
 230  ***/
 231 int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 232
 233 /****f* silcutil/silc_bit_fns
 234  *
 235  * SYNOPSIS
 236  *
 237  *    int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 238  *                     SilcUInt32 offset);
 239  *
 240  * DESCRIPTION
 241  *
 242  *    Returns the bit number of the next set bit in the `bitmap' of size
 243  *    of `bitmap_size' starting at bit `offset'.  Returns -1 on error or
 244  *    when there were no more set bits and sets silc_errno.
 245  *
 246  ***/
 247 int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 248                  SilcUInt32 offset);
 249
 250 /****f* silcutil/silc_bit_fnz
 251  *
 252  * SYNOPSIS
 253  *
 254  *    int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 255  *                     SilcUInt32 offset);
 256  *
 257  * DESCRIPTION
 258  *
 259  *    Returns the bit number of the next zero bit in the `bitmap' of size
 260  *    of `bitmap_size' starting at bit `offset'.  Returns -1 on error or
 261  *    when there were no more zero bits and sets silc_errno.
 262  *
 263  ***/
 264 int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 265                  SilcUInt32 offset);
 266
 267 /****f* silcutil/silc_bit_clear_bitmap
 268  *
 269  * SYNOPSIS
 270  *
 271  *    void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
 272  *                               SilcUInt32 bitmap_size);
 273  *
 274  * DESCRIPTION
 275  *
 276  *    Clears the whole bitmap.
 277  *
 278  ***/
 279 void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
 280                            SilcUInt32 bitmap_size);
 281
 282 #endif /* SILCBITOPS_H */