Cuckoo

This module implements a Cuckoo Filter.

Implementation Details

The implementation follows the specification as per the paper above.

For hashing we use the x64_128 variant of Murmur3 and the Erlang phash2.

Examples

iex> cf = Cuckoo.new(1000, 16, 4)
%Cuckoo.Filter{...}

iex> {:ok, cf} = Cuckoo.insert(cf, 5)
%Cuckoo.Filter{...}

iex> Cuckoo.contains?(cf, 5)
true

iex> {:ok, cf} = Cuckoo.delete(cf, 5)
%Cuckoo.Filter{...}

iex> Cuckoo.contains?(cf, 5)
false

Summary

contains?(filter, element)

Checks if the Cuckoo Filter contains element

delete!(filter, element)

Returns a filter with the removed element or raises Cuckoo.Error if an error occurs

delete(filter, element)

Attempts to delete element from the Cuckoo Filter if it contains it

insert!(filter, element)

Returns a filter with the inserted element or raises Cuckoo.Error if an error occurs

insert(filter, element)

Tries to insert element into the Cuckoo Filter

new(max_num_keys, fingerprint_size, fingerprints_per_bucket \\ 4)

Creates a new Cuckoo Filter using the given max_num_keys, fingerprint_size and fingerprints_per_bucket

Functions

contains?(filter, element)

Specs:

Checks if the Cuckoo Filter contains element.

Returns true if does, otherwise returns false.

delete(filter, element)

Specs:

Attempts to delete element from the Cuckoo Filter if it contains it.

Returns {:error, :inexistent} if the element doesn’t exist in the filter, otherwise returns {:ok, filter}.

delete!(filter, element)

Specs:

Returns a filter with the removed element or raises Cuckoo.Error if an error occurs.

insert(filter, element)

Specs:

Tries to insert element into the Cuckoo Filter.

Returns {:ok, filter} if successful, otherwise returns {:error, :full} from which you should consider the Filter to be full.

insert!(filter, element)

Specs:

Returns a filter with the inserted element or raises Cuckoo.Error if an error occurs.

new(max_num_keys, fingerprint_size, fingerprints_per_bucket \\ 4)

Specs:

Creates a new Cuckoo Filter using the given max_num_keys, fingerprint_size and fingerprints_per_bucket.

The suggested values for the last two according to one of the publications should be 16 and 4 respectively, as it allows the Cuckoo Filter to achieve a sweet spot in space effiency and table occupancy.