API Reference

This page provides a detailed reference for the public API of the CuckooFilter class, as defined in src/cuckoofilter.h.

cuckoofilter::Status Enum

All filter operations that can succeed or fail return a Status enum value.

enum Status {
  Ok = 0,             // Operation was successful.
  NotFound = 1,         // Item not found (for Contain or Delete).
  NotEnoughSpace = 2, // Filter is full and cannot accept a new item.
  NotSupported = 3,     // Operation is not supported.
};

cuckoofilter::CuckooFilter Class

The main class implementing the Cuckoo Filter.

Template Parameters

template <
    typename ItemType,
    size_t bits_per_item,
    template <size_t> class TableType = SingleTable,
    typename HashFamily = TwoIndependentMultiplyShift
>
class CuckooFilter { ... };
  • typename ItemType: The type of items stored in the filter.
  • size_t bits_per_item: The number of bits for each item's fingerprint.
  • template <size_t> class TableType: The storage table implementation. Defaults to SingleTable. Use PackedTable for semi-sorting.
  • typename HashFamily: The hash function family. Defaults to TwoIndependentMultiplyShift.

Constructor

explicit CuckooFilter(const size_t max_num_keys)

Creates a cuckoo filter instance.

  • Parameters:
    • max_num_keys: The maximum number of items you expect to store. The filter will automatically calculate an appropriate hash table size based on this value to maintain a high load factor (around 96%).

Public Methods

Status Add(const ItemType &item)

Adds an item to the filter.

  • Parameters:
    • item: The item to add.
  • Returns:
    • Ok: If the item was successfully inserted or placed in the victim cache.
    • NotEnoughSpace: If the filter is full and the victim cache is also occupied.

Status Contain(const ItemType &item) const

Checks if an item is in the filter.

  • Parameters:
    • item: The item to check.
  • Returns:
    • Ok: If the item is probably in the filter (could be a false positive).
    • NotFound: If the item is definitely not in the filter.

Status Delete(const ItemType &item)

Deletes an item from the filter.

  • Parameters:
    • item: The item to delete.
  • Returns:
    • Ok: If the item was found and deleted.
    • NotFound: If the item was not found in any of its potential locations.

size_t Size() const

Returns the number of items currently in the filter.

  • Returns: The count of items successfully added.

size_t SizeInBytes() const

Returns the total size of the filter's hash table in bytes.

  • Returns: The memory footprint of the underlying bucket storage.

std::string Info() const

Provides a summary of the filter's status and configuration.

  • Returns: A string containing information like table type, keys stored, load factor, and bits per key.