[#CuckooCache-cache]
= xref:CuckooCache.adoc[CuckooCache]::cache
:relfileprefix: ../
:mrdocs:

xref:CuckooCache/cache/2constructor.adoc[`cache`] implements a cache with properties similar to a cuckoo&hyphen;set&period;

== Synopsis

Declared in `&lt;cuckoocache&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    typename Element,
    typename Hash&gt;
class cache;
----

== Description

The cache is able to hold up to `(&#126;(uint32&lowbar;t)0) &hyphen; 1` elements&period;

Read Operations&colon;

* contains() for `erase&equals;false`

Read&plus;Erase Operations&colon;

* contains() for `erase&equals;true`

Erase Operations&colon;

* allow&lowbar;erase()

Write Operations&colon;

* setup()
* setup&lowbar;bytes()
* insert()
* please&lowbar;keep()

Synchronization Free Operations&colon;

* invalid()
* compute&lowbar;hashes()

User Must Guarantee&colon;

1&period; Write requires synchronized access (e&period;g&period; a lock) 2&period; Read requires no concurrent Write, synchronized with last insert&period; 3&period; Erase requires no concurrent Write, synchronized with last insert&period; 4&period; An Erase caller must release all memory before allowing a new Writer&period;

Note on function names&colon;

* The name &quot;allow&lowbar;erase&quot; is used because the real discard happens later&period;
* The name &quot;please&lowbar;keep&quot; is used because elements may be erased anyways on insert&period;

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:CuckooCache/cache/2constructor.adoc[`cache`]         [.small]#[constructor]#
| You must always construct a cache with some elements via a subsequent call to setup or setup&lowbar;bytes, otherwise operations may segfault&period;
| xref:CuckooCache/cache/TestOnlyReset.adoc[`TestOnlyReset`] 
| Empty the cache and re&hyphen;run setup()&period;
| xref:CuckooCache/cache/contains.adoc[`contains`] 
| contains iterates through the hash locations for a given element and checks to see if it is present&period;
| xref:CuckooCache/cache/insert.adoc[`insert`] 
| insert loops at most depth&lowbar;limit times trying to insert a hash at various locations in the table via a variant of the Cuckoo Algorithm with eight hash locations&period;
| xref:CuckooCache/cache/setup.adoc[`setup`] 
| setup initializes the container to store no more than new&lowbar;size elements and no less than 2 elements&period;
| xref:CuckooCache/cache/setup_bytes.adoc[`setup&lowbar;bytes`] 
| setup&lowbar;bytes is a convenience function which accounts for internal memory usage when deciding how many elements to store&period; It isn&apos;t perfect because it doesn&apos;t account for any overhead (struct size, MallocUsage, collection and epoch flags)&period; This was done to simplify selecting a power of two size&period; In the expected use case, an extra two bits per entry should be negligible compared to the size of the elements&period;
|===


== Template Parameters

[cols="1,4"]
|===
| Name| Description
| *Element*
| should be a movable and copyable type
| *Hash*
| should be a function&sol;callable which takes a template parameter hash&lowbar;select and an Element and extracts a hash from it&period; Should return high&hyphen;entropy uint32&lowbar;t hashes for `Hash h&semi; h&lt;0&gt;(e) &period;&period;&period; h&lt;7&gt;(e)`&period;
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#
