From add01e2dfd55ad953e7b62d6149b8f294d201cfe Mon Sep 17 00:00:00 2001 From: joaquintides Date: Sat, 13 May 2023 19:28:43 +0200 Subject: [PATCH] added compliance section for concurrent hashmap --- doc/unordered/compliance.adoc | 57 +++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/doc/unordered/compliance.adoc b/doc/unordered/compliance.adoc index bc53e36e..cd93770b 100644 --- a/doc/unordered/compliance.adoc +++ b/doc/unordered/compliance.adoc @@ -144,4 +144,61 @@ The main differences with C++ unordered associative containers are: ** Pointer stability is not kept under rehashing. ** There is no API for node extraction/insertion. +== Concurrent Hashmap + +There is currently no specification in the C++ standard for this or any other concurrent +data structure. `boost::concurrent_flat_map` takes the same template parameters as `std::unordered_map` +and all the maps provided by Boost.Unordered, and its API is modelled after that of +`boost::unordered_flat_map` with the crucial difference that iterators are not provided +due to their inherent problems in concurrent scenarios (high contention, prone to deadlocking): +so, `boost::concurrent_flat_map` is technically not a +https://en.cppreference.com/w/cpp/named_req/Container[Container^], although +it meets all the requirements of https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer[AllocatorAware^] +containers except those implying iterators. + +In a non-concurrent unordered container, iterators serve two main purposes: + +* Access to an element previously located via lookup. +* Container traversal. + +In place of iterators, `boost::unordered_flat_map` uses _internal visitation_ +facilities as a thread-safe substitute. Classical operations returning an iterator to an +element already existing in the container, like for instance: + +[source,c++] +---- +iterator find(const key_type& k); +std::pair insert(const value_type& obj); +---- + +are transformed to accept a _visitation function_ that is passed such element: + +[source,c++] +---- +template size_t visit(const key_type& k, F f); +template bool insert_or_visit(const value_type& obj, F f); +---- + +(In the second case `f` is only invoked if there's an equivalent element +to `obj` in the table, not if insertion is successful). Container traversal +is served by: + +[source,c++] +---- +template size_t visit_all(F f); +---- + +of which there are parallelized version in C++17 compilers with parallel +algorithm support. In general, the interface of `boost::concurrent_flat_map` +is derived from that of `boost::unordered_flat_map` by a fairly straightforward +process of replacing iterators with visitation where applicable. If +`iterator` and `const_iterator` provide mutable and const access to elements, +respectively, here visitation is granted mutable or const access depending on +the constness of the member function used (there are also `*cvisit` overloads for +explicit const visitation). + +The one notable operation not provided is `operator[]`/`at`, which can be +replaced, if in a more convoluted manner, by +xref:#concurrent_flat_map_try_emplace_or_cvisit[`try_emplace_or_visit`]. + //-