5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcutil/Bit Operations Interface
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.
30 * Example with a pre-allocated bitmap:
32 * // Declare bitmap of size of 500 bits
33 * SILC_BITMAP_DECLARE(bitmap, 500);
34 * int bitmap_size = SILC_BITMAP_SIZE(500);
37 * silc_bit_set(bitmap, bitmap_size, 0);
39 * // Set bit number 100
40 * silc_bit_set(bitmap, bitmap_size, 100);
42 * // Find first set bit from the bitmap
43 * bit = silc_bit_ffs(bitmap, bitmap_size);
45 * // Find next set bit from the bitmap
46 * bit = silc_bit_fns(bitmap, bitmap_size, bit + 1);
48 * // Clear bit number 100
49 * silc_bit_set(bitmap, bitmap_size, 100);
56 #define SILC_BIT_SIZE (SILC_SIZEOF_LONG * 8)
58 /****d* silcutil/SILC_BITMAP_DECLARE
62 * #define SILC_BITMAP_DECLARE(name, bits)
66 * Macro that can be used to declare a pre-allocated bitmap named `name' of
67 * size of `bits' many bits.
70 #define SILC_BITMAP_DECLARE(name, bits) \
71 unsigned long name[SILC_BITMAP_SIZE(bits)]
73 /****d* silcutil/SILC_BITMAP_SIZE
77 * #define SILC_BITMAP_SIZE(bits)
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.
86 #define SILC_BITMAP_SIZE(bits) (((bits) + SILC_BIT_SIZE) / SILC_BIT_SIZE)
88 /****f* silcutil/silc_bit_set
92 * SilcBool silc_bit_set(volatile unsigned long *bitmap,
93 * SilcUInt32 bitmap_size, SilcUInt32 bit);
97 * Set bit number `bit' in the `bitmap' of size of `bitmap_size'. Returns
98 * FALSE on error and sets silc_errno.
101 SilcBool silc_bit_set(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
104 /****f* silcutil/silc_bit_clear
108 * SilcBool silc_bit_clear(volatile unsigned long *bitmap,
109 * SilcUInt32 bitmap_size, SilcUInt32 bit);
113 * Clear bit number `bit' in the `bitmap' of size of `bitmap_size'.
114 * Returns FALSE on error and sets silc_errno.
117 SilcBool silc_bit_clear(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
120 /****f* silcutil/silc_bit_toggle
124 * SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
125 * SilcUInt32 bitmap_size, SilcUInt32 bit);
129 * Toggle bit number `bit' in the `bitmap' of size of `bitmap_size'.
130 * Returns FALSE on error and sets silc_errno.
133 SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
134 SilcUInt32 bitmap_size, SilcUInt32 bit);
136 /****f* silcutil/silc_bit_test_and_set
140 * int silc_bit_test_and_set(volatile unsigned long *bitmap,
141 * SilcUInt32 bitmap_size, SilcUInt32 bit);
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
150 int silc_bit_test_and_set(volatile unsigned long *bitmap,
151 SilcUInt32 bitmap_size, SilcUInt32 bit);
153 /****f* silcutil/silc_bit_test_and_clear
157 * int silc_bit_test_and_clear(volatile unsigned long *bitmap,
158 * SilcUInt32 bitmap_size, SilcUInt32 bit);
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
167 int silc_bit_test_and_clear(volatile unsigned long *bitmap,
168 SilcUInt32 bitmap_size, SilcUInt32 bit);
170 /****f* silcutil/silc_bit_test_and_toggle
174 * int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
175 * SilcUInt32 bitmap_size, SilcUInt32 bit);
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
184 int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
185 SilcUInt32 bitmap_size, SilcUInt32 bit);
187 /****f* silcutil/silc_bit_get
191 * int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
196 * Returns the value of the bit number `bit' or -1 on error and sets
200 int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
203 /****f* silcutil/silc_bit_ffs
207 * int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
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.
216 int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
218 /****f* silcutil/silc_bit_ffz
222 * int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
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.
231 int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
233 /****f* silcutil/silc_bit_fns
237 * int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
238 * SilcUInt32 offset);
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.
247 int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
250 /****f* silcutil/silc_bit_fnz
254 * int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
255 * SilcUInt32 offset);
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.
264 int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
267 /****f* silcutil/silc_bit_clear_bitmap
271 * void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
272 * SilcUInt32 bitmap_size);
276 * Clears the whole bitmap.
279 void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
280 SilcUInt32 bitmap_size);
282 #endif /* SILCBITOPS_H */