5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 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/SILC 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.
28 * Example with a pre-allocated bitmap:
30 * // Declare bitmap of size of 500 bits
31 * SILC_BITMAP_DECLARE(bitmap, 500);
32 * int bitmap_size = SILC_BITMAP_SIZE(500);
35 * silc_bit_set(bitmap, bitmap_size, 0);
37 * // Set bit number 100
38 * silc_bit_set(bitmap, bitmap_size, 100);
40 * // Find first set bit from the bitmap
41 * bit = silc_bit_ffs(bitmap, bitmap_size);
43 * // Find next set bit from the bitmap
44 * bit = silc_bit_fns(bitmap, bitmap_size, bit + 1);
46 * // Clear bit number 100
47 * silc_bit_set(bitmap, bitmap_size, 100);
54 #define SILC_BIT_SIZE (SILC_SIZEOF_LONG * 8)
56 /****d* silcutil/SilcBitOpAPI/SILC_BITMAP_DECLARE
60 * #define SILC_BITMAP_DECLARE(name, bits)
64 * Macro that can be used to declare a pre-allocated bitmap named `name' of
65 * size of `bits' many bits.
68 #define SILC_BITMAP_DECLARE(name, bits) \
69 unsigned long name[SILC_BITMAP_SIZE(bits)]
71 /****d* silcutil/SilcBitOpAPI/SILC_BITMAP_SIZE
75 * #define SILC_BITMAP_SIZE(bits)
79 * Macro that returns the size of a bitmap array of size of `bits' many
80 * bits. The returned size can be given as argument to the SILC Bit
81 * Operations API functions.
84 #define SILC_BITMAP_SIZE(bits) (((bits) + SILC_BIT_SIZE) / SILC_BIT_SIZE)
86 /****f* silcutil/SilcBitOpAPI/silc_bit_set
90 * SilcBool silc_bit_set(volatile unsigned long *bitmap,
91 * SilcUInt32 bitmap_size, SilcUInt32 bit);
95 * Set bit number `bit' in the `bitmap' of size of `bitmap_size'. Returns
96 * FALSE on error and sets silc_errno.
99 SilcBool silc_bit_set(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
102 /****f* silcutil/SilcBitOpAPI/silc_bit_clear
106 * SilcBool silc_bit_clear(volatile unsigned long *bitmap,
107 * SilcUInt32 bitmap_size, SilcUInt32 bit);
111 * Clear bit number `bit' in the `bitmap' of size of `bitmap_size'.
112 * Returns FALSE on error and sets silc_errno.
115 SilcBool silc_bit_clear(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
118 /****f* silcutil/SilcBitOpAPI/silc_bit_toggle
122 * SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
123 * SilcUInt32 bitmap_size, SilcUInt32 bit);
127 * Toggle bit number `bit' in the `bitmap' of size of `bitmap_size'.
128 * Returns FALSE on error and sets silc_errno.
131 SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
132 SilcUInt32 bitmap_size, SilcUInt32 bit);
134 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_set
138 * int silc_bit_test_and_set(volatile unsigned long *bitmap,
139 * SilcUInt32 bitmap_size, SilcUInt32 bit);
143 * Set bit number `bit' in the `bitmap' of size of `bitmap_size' and
144 * return the value before setting. Returns -1 on error and sets
148 int silc_bit_test_and_set(volatile unsigned long *bitmap,
149 SilcUInt32 bitmap_size, SilcUInt32 bit);
151 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_clear
155 * int silc_bit_test_and_clear(volatile unsigned long *bitmap,
156 * SilcUInt32 bitmap_size, SilcUInt32 bit);
160 * Clear bit number `bit' in the `bitmap' of size of `bitmap_size' and
161 * return the value before setting. Returns -1 on error and sets
165 int silc_bit_test_and_clear(volatile unsigned long *bitmap,
166 SilcUInt32 bitmap_size, SilcUInt32 bit);
168 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_toggle
172 * int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
173 * SilcUInt32 bitmap_size, SilcUInt32 bit);
177 * Toggle bit number `bit' in the `bitmap' of size of `bitmap_size' and
178 * return the value before setting. Returns -1 on error and sets
182 int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
183 SilcUInt32 bitmap_size, SilcUInt32 bit);
185 /****f* silcutil/SilcBitOpAPI/silc_bit_get
189 * int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
194 * Returns the value of the bit number `bit' or -1 on error and sets
198 int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
201 /****f* silcutil/SilcBitOpAPI/silc_bit_ffs
205 * int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
209 * Returns the bit number of the first set bit in the `bitmap' of size
210 * of `bitmap_size'. Returns -1 on error or when there were no set bits
211 * and sets silc_errno.
214 int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
216 /****f* silcutil/SilcBitOpAPI/silc_bit_ffz
220 * int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
224 * Returns the bit number of the first zero bit in the `bitmap' of size
225 * of `bitmap_size'. Returns -1 on error or when there were no zero bits
226 * and sets silc_errno.
229 int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
231 /****f* silcutil/SilcBitOpAPI/silc_bit_fns
235 * int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
236 * SilcUInt32 offset);
240 * Returns the bit number of the next set bit in the `bitmap' of size
241 * of `bitmap_size' starting at bit `offset'. Returns -1 on error or
242 * when there were no more set bits and sets silc_errno.
245 int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
248 /****f* silcutil/SilcBitOpAPI/silc_bit_fnz
252 * int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
253 * SilcUInt32 offset);
257 * Returns the bit number of the next zero bit in the `bitmap' of size
258 * of `bitmap_size' starting at bit `offset'. Returns -1 on error or
259 * when there were no more zero bits and sets silc_errno.
262 int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
265 /****f* silcutil/SilcBitOpAPI/silc_bit_clear_bitmap
269 * void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
270 * SilcUInt32 bitmap_size);
274 * Clears the whole bitmap.
277 void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
278 SilcUInt32 bitmap_size);
280 #endif /* SILCBITOPS_H */