src/util/container_bloomfilter.c

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001, 2002, 2003, 2004, 2006, 2008 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 2, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20 /**
  21  * @file util/container_bloomfilter.c
  22  * @brief data structure used to reduce disk accesses.
  23  *
  24  * The idea basically: Create a signature for each element in the
  25  * database. Add those signatures to a bit array. When doing a lookup,
  26  * check if the bit array matches the signature of the requested
  27  * element. If yes, address the disk, otherwise return 'not found'.
  28  *
  29  * A property of the bloom filter is that sometimes we will have
  30  * a match even if the element is not on the disk (then we do
  31  * an unnecessary disk access), but what's most important is that
  32  * we never get a single "false negative".
  33  *
  34  * To be able to delete entries from the bloom filter, we maintain
  35  * a 4 bit counter in the file on the drive (we still use only one
  36  * bit in memory).
  37  *
  38  * @author Igor Wronsky
  39  * @author Christian Grothoff
  40  */
  41
  42 #include "platform.h"
  43 #include "gnunet_common.h"
  44 #include "gnunet_container_lib.h"
  45 #include "gnunet_disk_lib.h"
  46
  47 struct GNUNET_CONTAINER_BloomFilter
  48 {
  49
  50   /**
  51    * The actual bloomfilter bit array
  52    */
  53   char *bitArray;
  54
  55   /**
  56    * Filename of the filter
  57    */
  58   char *filename;
  59
  60   /**
  61    * The bit counter file on disk
  62    */
  63   struct GNUNET_DISK_FileHandle *fh;
  64
  65   /**
  66    * How many bits we set for each stored element
  67    */
  68   unsigned int addressesPerElement;
  69
  70   /**
  71    * Size of bitArray in bytes
  72    */
  73   size_t bitArraySize;
  74
  75 };
  76
  77
  78 /**
  79  * Sets a bit active in the bitArray. Increment bit-specific
  80  * usage counter on disk only if below 4bit max (==15).
  81  *
  82  * @param bitArray memory area to set the bit in
  83  * @param bitIdx which bit to set
  84  */
  85 static void
  86 setBit (char *bitArray, unsigned int bitIdx)
  87 {
  88   size_t arraySlot;
  89   unsigned int targetBit;
  90
  91   arraySlot = bitIdx / 8;
  92   targetBit = (1L << (bitIdx % 8));
  93   bitArray[arraySlot] |= targetBit;
  94 }
  95
  96 /**
  97  * Clears a bit from bitArray. Bit is cleared from the array
  98  * only if the respective usage counter on the disk hits/is zero.
  99  *
 100  * @param bitArray memory area to set the bit in
 101  * @param bitIdx which bit to unset
 102  */
 103 static void
 104 clearBit (char *bitArray, unsigned int bitIdx)
 105 {
 106   size_t slot;
 107   unsigned int targetBit;
 108
 109   slot = bitIdx / 8;
 110   targetBit = (1L << (bitIdx % 8));
 111   bitArray[slot] = bitArray[slot] & (~targetBit);
 112 }
 113
 114 /**
 115  * Checks if a bit is active in the bitArray
 116  *
 117  * @param bitArray memory area to set the bit in
 118  * @param bitIdx which bit to test
 119  * @return GNUNET_YES if the bit is set, GNUNET_NO if not.
 120  */
 121 static int
 122 testBit (char *bitArray, unsigned int bitIdx)
 123 {
 124   size_t slot;
 125   unsigned int targetBit;
 126
 127   slot = bitIdx / 8;
 128   targetBit = (1L << (bitIdx % 8));
 129   if (bitArray[slot] & targetBit)
 130     return GNUNET_YES;
 131   else
 132     return GNUNET_NO;
 133 }
 134
 135 /**
 136  * Sets a bit active in the bitArray and increments
 137  * bit-specific usage counter on disk (but only if
 138  * the counter was below 4 bit max (==15)).
 139  *
 140  * @param bitArray memory area to set the bit in
 141  * @param bitIdx which bit to test
 142  * @param fh A file to keep the 4 bit address usage counters in
 143  */
 144 static void
 145 incrementBit (char *bitArray, unsigned int bitIdx, const struct GNUNET_DISK_FileHandle *fh)
 146 {
 147   off_t fileSlot;
 148   unsigned char value;
 149   unsigned int high;
 150   unsigned int low;
 151   unsigned int targetLoc;
 152
 153   setBit (bitArray, bitIdx);
 154   if (GNUNET_DISK_handle_invalid (fh))
 155     return;
 156   /* Update the counter file on disk */
 157   fileSlot = bitIdx / 2;
 158   targetLoc = bitIdx % 2;
 159
 160   GNUNET_assert (fileSlot ==
 161                  GNUNET_DISK_file_seek (fh, fileSlot, GNUNET_DISK_SEEK_SET));
 162   if (1 != GNUNET_DISK_file_read (fh, &value, 1))
 163     value = 0;
 164   low = value & 0xF;
 165   high = (value & (~0xF)) >> 4;
 166
 167   if (targetLoc == 0)
 168     {
 169       if (low < 0xF)
 170         low++;
 171     }
 172   else
 173     {
 174       if (high < 0xF)
 175         high++;
 176     }
 177   value = ((high << 4) | low);
 178   GNUNET_assert (fileSlot == GNUNET_DISK_file_seek (fh,
 179                                                     fileSlot,
 180                                                     GNUNET_DISK_SEEK_SET));
 181   GNUNET_assert (1 == GNUNET_DISK_file_write (fh, &value, 1));
 182 }
 183
 184 /**
 185  * Clears a bit from bitArray if the respective usage
 186  * counter on the disk hits/is zero.
 187  *
 188  * @param bitArray memory area to set the bit in
 189  * @param bitIdx which bit to test
 190  * @param fh A file to keep the 4bit address usage counters in
 191  */
 192 static void
 193 decrementBit (char *bitArray, unsigned int bitIdx, const struct GNUNET_DISK_FileHandle *fh)
 194 {
 195   off_t fileSlot;
 196   unsigned char value;
 197   unsigned int high;
 198   unsigned int low;
 199   unsigned int targetLoc;
 200
 201   if (GNUNET_DISK_handle_invalid (fh))
 202     return;                     /* cannot decrement! */
 203   /* Each char slot in the counter file holds two 4 bit counters */
 204   fileSlot = bitIdx / 2;
 205   targetLoc = bitIdx % 2;
 206   GNUNET_DISK_file_seek (fh, fileSlot, GNUNET_DISK_SEEK_SET);
 207   if (1 != GNUNET_DISK_file_read (fh, &value, 1))
 208     value = 0;
 209   low = value & 0xF;
 210   high = (value & 0xF0) >> 4;
 211
 212   /* decrement, but once we have reached the max, never go back! */
 213   if (targetLoc == 0)
 214     {
 215       if ((low > 0) && (low < 0xF))
 216         low--;
 217       if (low == 0)
 218         {
 219           clearBit (bitArray, bitIdx);
 220         }
 221     }
 222   else
 223     {
 224       if ((high > 0) && (high < 0xF))
 225         high--;
 226       if (high == 0)
 227         {
 228           clearBit (bitArray, bitIdx);
 229         }
 230     }
 231   value = ((high << 4) | low);
 232   GNUNET_DISK_file_seek (fh, fileSlot, GNUNET_DISK_SEEK_SET);
 233   GNUNET_assert (1 == GNUNET_DISK_file_write (fh, &value, 1));
 234 }
 235
 236 #define BUFFSIZE 65536
 237
 238 /**
 239  * Creates a file filled with zeroes
 240  *
 241  * @param fh the file handle
 242  * @param size the size of the file
 243  * @return GNUNET_OK if created ok, GNUNET_SYSERR otherwise
 244  */
 245 static int
 246 makeEmptyFile (const struct GNUNET_DISK_FileHandle *fh,
 247                size_t size)
 248 {
 249   char *buffer;
 250   size_t bytesleft = size;
 251   int res = 0;
 252
 253   if (GNUNET_DISK_handle_invalid (fh))
 254     return GNUNET_SYSERR;
 255   buffer = GNUNET_malloc (BUFFSIZE);
 256   memset (buffer, 0, BUFFSIZE);
 257   GNUNET_DISK_file_seek (fh, 0, GNUNET_DISK_SEEK_SET);
 258
 259   while (bytesleft > 0)
 260     {
 261       if (bytesleft > BUFFSIZE)
 262         {
 263           res = GNUNET_DISK_file_write (fh, buffer, BUFFSIZE);
 264           bytesleft -= BUFFSIZE;
 265         }
 266       else
 267         {
 268           res = GNUNET_DISK_file_write (fh, buffer, bytesleft);
 269           bytesleft = 0;
 270         }
 271       GNUNET_assert (res != GNUNET_SYSERR);
 272     }
 273   GNUNET_free (buffer);
 274   return GNUNET_OK;
 275 }
 276
 277 /* ************** GNUNET_CONTAINER_BloomFilter iterator ********* */
 278
 279 /**
 280  * Iterator (callback) method to be called by the
 281  * bloomfilter iterator on each bit that is to be
 282  * set or tested for the key.
 283  *
 284  * @param cls closure
 285  * @param bf the filter to manipulate
 286  * @param bit the current bit
 287  */
 288 typedef void (*BitIterator) (void *cls,
 289                              struct GNUNET_CONTAINER_BloomFilter * bf,
 290                              unsigned int bit);
 291
 292 /**
 293  * Call an iterator for each bit that the bloomfilter
 294  * must test or set for this element.
 295  *
 296  * @param bf the filter
 297  * @param callback the method to call
 298  * @param arg extra argument to callback
 299  * @param key the key for which we iterate over the BF bits
 300  */
 301 static void
 302 iterateBits (struct GNUNET_CONTAINER_BloomFilter *bf,
 303              BitIterator callback, void *arg, const GNUNET_HashCode * key)
 304 {
 305   GNUNET_HashCode tmp[2];
 306   int bitCount;
 307   int round;
 308   unsigned int slot = 0;
 309
 310   bitCount = bf->addressesPerElement;
 311   memcpy (&tmp[0], key, sizeof (GNUNET_HashCode));
 312   round = 0;
 313   while (bitCount > 0)
 314     {
 315       while (slot < (sizeof (GNUNET_HashCode) / sizeof (uint32_t)))
 316         {
 317           callback (arg,
 318                     bf,
 319                     (((uint32_t *) &tmp[round & 1])[slot]) &
 320                     ((bf->bitArraySize * 8) - 1));
 321           slot++;
 322           bitCount--;
 323           if (bitCount == 0)
 324             break;
 325         }
 326       if (bitCount > 0)
 327         {
 328           GNUNET_CRYPTO_hash (&tmp[round & 1], sizeof (GNUNET_HashCode),
 329                               &tmp[(round + 1) & 1]);
 330           round++;
 331           slot = 0;
 332         }
 333     }
 334 }
 335
 336 /**
 337  * Callback: increment bit
 338  *
 339  * @param cls not used
 340  * @param bf the filter to manipulate
 341  * @param bit the bit to increment
 342  */
 343 static void
 344 incrementBitCallback (void *cls,
 345                       struct GNUNET_CONTAINER_BloomFilter *bf,
 346                       unsigned int bit)
 347 {
 348   incrementBit (bf->bitArray, bit, bf->fh);
 349 }
 350
 351 /**
 352  * Callback: decrement bit
 353  *
 354  * @param cls not used
 355  * @param bf the filter to manipulate
 356  * @param bit the bit to decrement
 357  */
 358 static void
 359 decrementBitCallback (void *cls,
 360                       struct GNUNET_CONTAINER_BloomFilter *bf,
 361                       unsigned int bit)
 362 {
 363   decrementBit (bf->bitArray, bit, bf->fh);
 364 }
 365
 366 /**
 367  * Callback: test if all bits are set
 368  *
 369  * @param cls pointer set to GNUNET_NO if bit is not set
 370  * @param bf the filter
 371  * @param bit the bit to test
 372  */
 373 static void
 374 testBitCallback (void *cls,
 375                  struct GNUNET_CONTAINER_BloomFilter *bf, unsigned int bit)
 376 {
 377   int *arg = cls;
 378   if (GNUNET_NO == testBit (bf->bitArray, bit))
 379     *arg = GNUNET_NO;
 380 }
 381
 382 /* *********************** INTERFACE **************** */
 383
 384 /**
 385  * Load a bloom-filter from a file.
 386  *
 387  * @param filename the name of the file (or the prefix)
 388  * @param size the size of the bloom-filter (number of
 389  *        bytes of storage space to use)
 390  * @param k the number of GNUNET_CRYPTO_hash-functions to apply per
 391  *        element (number of bits set per element in the set)
 392  * @return the bloomfilter
 393  */
 394 struct GNUNET_CONTAINER_BloomFilter *
 395 GNUNET_CONTAINER_bloomfilter_load (const char *filename,
 396                                    size_t size,
 397                                    unsigned int k)
 398 {
 399   struct GNUNET_CONTAINER_BloomFilter *bf;
 400   char *rbuff;
 401   off_t pos;
 402   int i;
 403   size_t ui;
 404
 405   if ((k == 0) || (size == 0))
 406     return NULL;
 407   if (size < BUFFSIZE)
 408     size = BUFFSIZE;
 409   ui = 1;
 410   while (ui < size)
 411     ui *= 2;
 412   size = ui;                    /* make sure it's a power of 2 */
 413
 414   bf = GNUNET_malloc (sizeof (struct GNUNET_CONTAINER_BloomFilter));
 415   /* Try to open a bloomfilter file */
 416   if (filename != NULL)
 417     {
 418       bf->fh = GNUNET_DISK_file_open (filename, GNUNET_DISK_OPEN_READWRITE
 419                                       | GNUNET_DISK_OPEN_CREATE,
 420           GNUNET_DISK_PERM_USER_READ | GNUNET_DISK_PERM_USER_WRITE);
 421       if (NULL == bf->fh)
 422         {
 423           GNUNET_free (bf);
 424           return NULL;
 425         }
 426       bf->filename = GNUNET_strdup (filename);
 427     }
 428   else
 429     {
 430       bf->filename = NULL;
 431       bf->fh = NULL;
 432     }
 433   /* Alloc block */
 434   bf->bitArray = GNUNET_malloc_large (size);
 435   bf->bitArraySize = size;
 436   bf->addressesPerElement = k;
 437   memset (bf->bitArray, 0, bf->bitArraySize);
 438
 439   if (bf->filename != NULL)
 440     {
 441       /* Read from the file what bits we can */
 442       rbuff = GNUNET_malloc (BUFFSIZE);
 443       pos = 0;
 444       while (pos < size * 8)
 445         {
 446           int res;
 447
 448           res = GNUNET_DISK_file_read (bf->fh, rbuff, BUFFSIZE);
 449           if (res == -1)
 450             {
 451               GNUNET_log_strerror_file (GNUNET_ERROR_TYPE_WARNING,
 452                                         "read",
 453                                         bf->filename);
 454             }
 455           if (res == 0)
 456             break;              /* is ok! we just did not use that many bits yet */
 457           for (i = 0; i < res; i++)
 458             {
 459               if ((rbuff[i] & 0x0F) != 0)
 460                 setBit (bf->bitArray, pos + i * 2);
 461               if ((rbuff[i] & 0xF0) != 0)
 462                 setBit (bf->bitArray, pos + i * 2 + 1);
 463             }
 464           if (res < BUFFSIZE)
 465             break;
 466           pos += BUFFSIZE * 2;  /* 2 bits per byte in the buffer */
 467         }
 468       GNUNET_free (rbuff);
 469     }
 470   return bf;
 471 }
 472
 473
 474 /**
 475  * Create a bloom filter from raw bits.
 476  *
 477  * @param data the raw bits in memory (maybe NULL,
 478  *        in which case all bits should be considered
 479  *        to be zero).
 480  * @param size the size of the bloom-filter (number of
 481  *        bytes of storage space to use); also size of data
 482  *        -- unless data is NULL
 483  * @param k the number of GNUNET_CRYPTO_hash-functions to apply per
 484  *        element (number of bits set per element in the set)
 485  * @return the bloomfilter
 486  */
 487 struct GNUNET_CONTAINER_BloomFilter *
 488 GNUNET_CONTAINER_bloomfilter_init (const char *data,
 489                                    size_t size,
 490                                    unsigned int k)
 491 {
 492   struct GNUNET_CONTAINER_BloomFilter *bf;
 493   size_t ui;
 494
 495   if ((k == 0) || (size == 0))
 496     return NULL;
 497   ui = 1;
 498   while (ui < size)
 499     ui *= 2;
 500   if (size != ui)
 501     {
 502       GNUNET_break (0);
 503       return NULL;
 504     }
 505   bf = GNUNET_malloc (sizeof (struct GNUNET_CONTAINER_BloomFilter));
 506   bf->filename = NULL;
 507   bf->fh = NULL;
 508   bf->bitArray = GNUNET_malloc_large (size);
 509   bf->bitArraySize = size;
 510   bf->addressesPerElement = k;
 511   if (data != NULL)
 512     memcpy (bf->bitArray, data, size);
 513   else
 514     memset (bf->bitArray, 0, bf->bitArraySize);
 515   return bf;
 516 }
 517
 518
 519 /**
 520  * Copy the raw data of this bloomfilter into
 521  * the given data array.
 522  *
 523  * @param data where to write the data
 524  * @param size the size of the given data array
 525  * @return GNUNET_SYSERR if the data array is not big enough
 526  */
 527 int
 528 GNUNET_CONTAINER_bloomfilter_get_raw_data (struct GNUNET_CONTAINER_BloomFilter
 529                                            *bf, char *data,
 530                                            size_t size)
 531 {
 532   if (NULL == bf)
 533     return GNUNET_SYSERR;
 534
 535   if (bf->bitArraySize != size)
 536     return GNUNET_SYSERR;
 537   memcpy (data, bf->bitArray, size);
 538   return GNUNET_OK;
 539 }
 540
 541 /**
 542  * Free the space associated with a filter
 543  * in memory, flush to drive if needed (do not
 544  * free the space on the drive)
 545  *
 546  * @param bf the filter
 547  */
 548 void
 549 GNUNET_CONTAINER_bloomfilter_free (struct GNUNET_CONTAINER_BloomFilter *bf)
 550 {
 551   if (NULL == bf)
 552     return;
 553   if (bf->filename != NULL)
 554     {
 555       GNUNET_DISK_file_close (bf->fh);
 556       GNUNET_free (bf->filename);
 557     }
 558   GNUNET_free (bf->bitArray);
 559   GNUNET_free (bf);
 560 }
 561
 562 /**
 563  * Reset a bloom filter to empty. Clears the file on disk.
 564  *
 565  * @param bf the filter
 566  */
 567 void
 568 GNUNET_CONTAINER_bloomfilter_clear (struct GNUNET_CONTAINER_BloomFilter *bf)
 569 {
 570   if (NULL == bf)
 571     return;
 572
 573   memset (bf->bitArray, 0, bf->bitArraySize);
 574   if (bf->filename != NULL)
 575     makeEmptyFile (bf->fh, bf->bitArraySize * 4);
 576 }
 577
 578
 579 /**
 580  * Test if an element is in the filter.
 581  *
 582  * @param e the element
 583  * @param bf the filter
 584  * @return GNUNET_YES if the element is in the filter, GNUNET_NO if not
 585  */
 586 int
 587 GNUNET_CONTAINER_bloomfilter_test (struct GNUNET_CONTAINER_BloomFilter *bf,
 588                                    const GNUNET_HashCode * e)
 589 {
 590   int res;
 591
 592   if (NULL == bf)
 593     return GNUNET_YES;
 594   res = GNUNET_YES;
 595   iterateBits (bf, &testBitCallback, &res, e);
 596   return res;
 597 }
 598
 599 /**
 600  * Add an element to the filter
 601  *
 602  * @param bf the filter
 603  * @param e the element
 604  */
 605 void
 606 GNUNET_CONTAINER_bloomfilter_add (struct GNUNET_CONTAINER_BloomFilter *bf,
 607                                   const GNUNET_HashCode * e)
 608 {
 609
 610   if (NULL == bf)
 611     return;
 612   iterateBits (bf, &incrementBitCallback, NULL, e);
 613 }
 614
 615
 616 /**
 617  * Or the entries of the given raw data array with the
 618  * data of the given bloom filter.  Assumes that
 619  * the size of the data array and the current filter
 620  * match.
 621  *
 622  * @param bf the filter
 623  * @param data the data to or-in
 624  * @param size number of bytes in data
 625  */
 626 int
 627 GNUNET_CONTAINER_bloomfilter_or (struct GNUNET_CONTAINER_BloomFilter *bf,
 628                                  const char *data,
 629                                  size_t size)
 630 {
 631   unsigned int i;
 632
 633   if (NULL == bf)
 634     return GNUNET_YES;
 635   if (bf->bitArraySize != size)
 636     return GNUNET_SYSERR;
 637   /* FIXME: we could do this 4-8x faster by
 638      going over int/long arrays */
 639   for (i = 0; i < size; i++)
 640     bf->bitArray[i] |= data[i];
 641   return GNUNET_OK;
 642 }
 643
 644 /**
 645  * Remove an element from the filter.
 646  *
 647  * @param bf the filter
 648  * @param e the element to remove
 649  */
 650 void
 651 GNUNET_CONTAINER_bloomfilter_remove (struct GNUNET_CONTAINER_BloomFilter *bf,
 652                                      const GNUNET_HashCode * e)
 653 {
 654   if (NULL == bf)
 655     return;
 656   if (bf->filename == NULL)
 657     return;
 658   iterateBits (bf, &decrementBitCallback, NULL, e);
 659 }
 660
 661 /**
 662  * Resize a bloom filter.  Note that this operation
 663  * is pretty costly.  Essentially, the bloom filter
 664  * needs to be completely re-build.
 665  *
 666  * @param bf the filter
 667  * @param iterator an iterator over all elements stored in the BF
 668  * @param iterator_arg argument to the iterator function
 669  * @param size the new size for the filter
 670  * @param k the new number of GNUNET_CRYPTO_hash-function to apply per element
 671  */
 672 void
 673 GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
 674                                      GNUNET_HashCodeIterator iterator,
 675                                      void *iterator_arg,
 676                                      size_t size,
 677                                      unsigned int k)
 678 {
 679   GNUNET_HashCode hc;
 680   unsigned int i;
 681
 682   GNUNET_free (bf->bitArray);
 683   i = 1;
 684   while (i < size)
 685     i *= 2;
 686   size = i;                     /* make sure it's a power of 2 */
 687
 688   bf->bitArraySize = size;
 689   bf->bitArray = GNUNET_malloc (size);
 690   memset (bf->bitArray, 0, bf->bitArraySize);
 691   if (bf->filename != NULL)
 692     makeEmptyFile (bf->fh, bf->bitArraySize * 4);
 693   while (GNUNET_YES == iterator (iterator_arg, &hc))
 694     GNUNET_CONTAINER_bloomfilter_add (bf, &hc);
 695 }
 696
 697 /* end of container_bloomfilter.c */