map

template<typename Key, typename Value>
class map : public ygm::container::detail::base_async_insert_key_value<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_async_insert_or_assign<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_misc<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_contains<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_count<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_async_reduce<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_async_erase_key<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_async_erase_key_value<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_batch_erase_key_value<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_async_visit<map<Key, Value>, std::tuple<Key, Value>>, public ygm::container::detail::base_iterators<map<Key, Value>>, public ygm::container::detail::base_iteration_key_value<map<Key, Value>, std::tuple<Key, Value>>

Public Types

using self_type = map<Key, Value>
using mapped_type = Value
using ptr_type = typename ygm::ygm_ptr<self_type>
using key_type = Key
using size_type = size_t
using for_all_args = std::tuple<Key, Value>
using container_type = ygm::container::map_tag
using iterator = typename local_container_type::iterator
using const_iterator = typename local_container_type::const_iterator

Public Functions

map() = delete
inline map(ygm::comm &comm)

Map constructor.

Parameters:

comm – Communicator to use for communication

inline map(ygm::comm &comm, const mapped_type &default_value)

Map constructor taking default value.

Parameters:

  • comm – Communicator to use for communication

  • default_value – Value to initialize all stored items with

inline map(ygm::comm &comm, std::initializer_list<std::pair<Key, Value>> l)

Map constructor from std::initializer_list of key-value pairs.

Initializer list is assumed to be replicated on all ranks.

Parameters:

  • comm – Communicator to use for communication

  • l – Initializer list of key-value pairs to put in map

template<typename STLContainer>
inline map(ygm::comm &comm, const STLContainer &cont)

Construct map from existing STL container.

Template Parameters:

T – Existing container type

Parameters:

  • comm – Communicator to use for communication

  • cont – STL container containing key-value pairs to put in map

template<typename YGMContainer>
inline map(ygm::comm &comm, const YGMContainer &yc)

Construct map from existing YGM container of key-value pairs.

Requires input container for_all_args to be a single item that is itself a key-value pair.

Template Parameters:

T – Existing container type

Parameters:

  • comm – Communicator to use for communication

  • yc – YGM container of key-value pairs to put in map.

inline ~map()
inline map(const self_type &other)
inline map(self_type &&other) noexcept
inline map &operator=(const self_type &other)
inline map &operator=(self_type &&other)
inline iterator local_begin()

Access to begin iterator of locally-held items.

Does not call barrier().

Returns:

Local iterator to beginning of items held by process.

inline const_iterator local_begin() const

Access to begin const_iterator of locally-held items for const map.

Does not call barrier().

Returns:

Local const iterator to beginning of items held by process.

inline const_iterator local_cbegin() const

Access to begin const_iterator of locally-held items for const map.

Does not call barrier().

Returns:

Local const iterator to beginning of items held by process.

inline iterator local_end()

Access to end iterator of locally-held items.

Does not call barrier().

Returns:

Local iterator to ending of items held by process.

inline const_iterator local_end() const

Access to end const_iterator of locally-held items for const map.

Does not call barrier().

Returns:

Local const iterator to ending of items held by process.

inline const_iterator local_cend() const

Access to end const_iterator of locally-held items for const map.

Does not call barrier().

Returns:

Local const iterator to ending of items held by process.

inline void local_insert(const key_type &key)

Insert a key and default value into local storage.

Parameters:

key – Local index to store default value at

inline void local_erase(const key_type &key)

Erase local entry for given key.

Parameters:

key – Key to erase from local storage

inline void local_erase(const key_type &key, const key_type &value)

Erase local entry for given key and value.

Does not erase the entry if key is found with a different value

Parameters:

  • key – Key to erase from local storage

  • value – Value to erase if associated to key

inline void local_insert(const key_type &key, const mapped_type &value)

Insert a key and value into local storage.

Parameters:

  • key – Local index to store value at

  • value – Value to store

inline void local_insert_or_assign(const key_type &key, const mapped_type &value)

Insert a key and value into local storage or assign value to key if key is already present.

Parameters:

  • key – Local index to store value at

  • value – Value to store

inline void local_clear()

Clear local storage.

template<typename ReductionOp>
inline void local_reduce(const key_type &key, const mapped_type &value, ReductionOp reducer)

Update a locally stored element by performing a binary operation between it and a provided value.

Template Parameters:

ReductionOp – functor type

Parameters:

  • key – Key to perform binary operation at.

  • value – Value to combine with the currently-held value

  • reducer – Binary operation to perform

inline size_t local_size() const

Get the number of elements stored on the local process.

Returns:

Local size of map

inline mapped_type &local_at(const key_type &key)

Retrieve value for given key.

Throws an exception if key is not found in local storage

Parameters:

key – Key to look up value for

inline const mapped_type &local_at(const key_type &key) const

Retrieve const reference to value for given key.

Throws an exception if key is not found in local storage

Parameters:

key – Key to look up value for

template<typename Function, typename ...VisitorArgs>
inline void local_visit(const key_type &key, Function &&fn, const VisitorArgs&... args)

Visit a key-value pair stored locally.

Template Parameters:

  • Function – functor type

  • VisitorArgs... – Variadic argument types

Parameters:

  • key – Key to visit

  • fn – User-provided function to execute at item

  • args... – Arguments to pass to user functor

template<typename Function, typename ...VisitorArgs>
inline void local_visit_if_contains(const key_type &key, Function &&fn, const VisitorArgs&... args)

Visit a key-value pair stored locally if the key is found.

Does not create an entry if key is not already found in local map

Template Parameters:

  • Function – functor type

  • VisitorArgs... – Variadic argument types

Parameters:

  • key – Key to visit

  • fn – User-provided function to execute at item

  • args... – Arguments to pass to user functor

template<typename Function, typename ...VisitorArgs>
inline void local_visit_if_contains(const key_type &key, Function &&fn, const VisitorArgs&... args) const

local_visit_if_contains for const containers

Does not create an entry if key is not already found in local map. fn is given a const key and value for execution.

Template Parameters:

  • Function – functor type

  • VisitorArgs... – Variadic argument types

Parameters:

  • key – Key to visit

  • fn – User-provided function to execute at item

  • args... – Arguments to pass to user functor

template<typename STLKeyContainer>
inline std::map<key_type, mapped_type> gather_keys(const STLKeyContainer &keys)

Collective operation to look up key-value pairs from each rank.

Parameters:

keys – Keys local rank wants to collect values for

Returns:

std::map of provided keys and their values

inline std::vector<mapped_type> local_get(const key_type &key) const

Retrieve all values associated to a given key.

Currently, ygm::container::map is not a multi-map, so there can be at most one value associated to each key.

Parameters:

key – Key to retrieve values for

Returns:

Vector of values associated to key

template<typename Function>
inline void local_for_all(Function &&fn)

Execute a functor on every locally-held key and value.

Template Parameters:

Function – functor type

Parameters:

fn – Functor to execute on keys and values

template<typename Function>
inline void local_for_all(Function &&fn) const

local_for_all for const containers

const references to key and value are provided to fn

Template Parameters:

Function – functor type

Parameters:

fn – Functor to execute on keys and values

inline size_t local_count(const key_type &key) const

Count the number of times a given key is found locally.

Returns:

Number of times key is found locally

inline bool local_contains(const key_type &key) const

Check if a key exists locally.

Parameters:

key – key to check for

Returns:

True if key exists locally, false otherwise

inline void local_swap(self_type &other)

Swap the local contents of a map.

Parameters:

other – The map to swap local contents with

inline void async_insert(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key, const typename std::tuple_element<1, std::tuple<Key, Value>>::type &value)

Asynchronously insert a key-value pair into a container.

The container’s local_insert() function is free to determine the behavior when key is already in the container

ygm::container::map<int, std::string> my_map(world);
my_map.async_insert(1, "one");
Parameters:

  • key – Key to insert

  • value – Value to associate to key

inline void async_insert(const std::pair<const typename std::tuple_element<0, std::tuple<Key, Value>>::type, typename std::tuple_element<1, std::tuple<Key, Value>>::type> &kvp)

Asynchronously insert a key-value pair into a container.

Equivalent to async_insert(kvp.first, kvp.second)

Parameters:

kvp – Key-value pair to insert

inline void async_insert_or_assign(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key, const typename std::tuple_element<1, std::tuple<Key, Value>>::type &value)

Asynchronously insert (key, value) pair into container if it does not already exist or assign value to key if key already exists in the container.

Behavior is meant to mirror std::map::insert_or_assign

Parameters:

  • key – Key to attempt insertion of

  • value – Value to associate with key

inline void async_insert_or_assign(const std::pair<typename std::tuple_element<0, std::tuple<Key, Value>>::type, typename std::tuple_element<1, std::tuple<Key, Value>>::type> &kvp)

Asynchronously insert (key, value) pair into container if it does not already exist or assign value to key if key already exists in the container.

Equivalent to async_insert_or_assign(kvp.first, kvp.second)

Parameters:

kvp – Key-value pair to attempt to insert

inline size_t size() const

Gets number of elements in a YGM container.

Returns:

Container size

inline void clear()

Clears the contents of a YGM container.

inline void swap(map<Key, Value> &other)

Swaps the contents of a YGM container.

Parameters:

other – Container to swap with

inline ygm::comm &comm() const

Access to underlying YGM communicator.

Returns:

YGM communicator used for communication by container

inline ygm::ygm_ptr<map<Key, Value>> get_ygm_ptr()

Access to the ygm_ptr used by the container.

Returns:

ygm_ptr used by the container when identifying itself in async calls on the ygm::comm

inline const ygm::ygm_ptr<map<Key, Value>> get_ygm_ptr() const

Const access to the ygm ptr used by the container.

Returns:

ygm_ptr to const version of container

inline bool contains(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &value) const

Checks for the presence of a value within a container.

Parameters:

value – Value to search for within container (key in the case of containers with keys)

Returns:

True if value exists in container; false otherwise.

inline size_t count(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &value) const

Counts all occurrences of a value within a container.

Parameters:

value – Value to search for within container (key in the case of containers with keys)

Returns:

Count of times value is seen in container

inline void async_reduce(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key, const typename std::tuple_element<1, std::tuple<Key, Value>>::type &value, ReductionOp reducer)

Combines existing mapped_type item with value using a user-provided binary operation if key is found in container. Inserts default mapped_type prior to reduction if key does not already exist in container. 

ygm::container::map<std::string, int> my_map(world);
my_map.async_insert("one", 1);
if (world.rank0()) {
   my_map.async_reduce("one", 2, std::plus<int>());
   my_map.async_reduce("two", 2, std::plus<int>());
}
world.barrier()
will result in my_map containing the pairs ("one", 3) and ("two", 2).

Template Parameters:

ReductionOp – Type of function provided by usert to perform reduction

Parameters:

  • key – Key to search for within container

  • value – Provided value to combine with existing value in container

inline void async_erase(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key)

Asynchronously erases a key from a container.

Parameters:

key – Key to erase (key, value) pair of in containers with keys and values or value to erase in containers without keys

inline void async_erase(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key, const typename std::tuple_element<1, std::tuple<Key, Value>>::type &value)

Asynchronously erases key and value from a container.

Does nothing if (key, value) pair is not found.

Parameters:

  • key – Key to find in container

  • value – Value to find associated to key

inline void erase(const Container &cont)

Erases key-value pairs found in a ygm::container with a for_all() method from the calling container.

This variation requires the container of key-value pairs to erase to have a for_all_args that is a tuple containing two items.

Template Parameters:

Container – YGM container type holding key-value pairs to erase

Parameters:

cont – YGM container of key-value pairs to erase

inline void erase(const Container &cont)

Erases key-value pairs found in a ygm::container with a for_all() method from the calling container.

This variation requires the container of key-value pairs to erase to have a for_all_args that is a tuple containing a single item that is itself a tuple of two items. This allows storing key-value pairs to erase in a ygm::container::bag, for instance.

Template Parameters:

Container – YGM container type holding key-value pairs to erase

Parameters:

cont – YGM container of key-value pairs to erase

inline void erase(const Container &cont)

Erases key-value pairs found in an STL container from the calling YGM container.

Template Parameters:

Container – STL container type

Parameters:

cont – STL container of key-value pairs to erase

Returns:

This variant requires the STL container to have a value_type that is a tuple containing key-value pairs.

inline void erase(const Container &cont)
inline void erase(const Container &cont)
inline void async_visit(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key, Visitor &&visitor, const VisitorArgs&... args)

Asynchronously visit key within a container and execute a user-provided function. 

ygm::container::map<std::string, int> my_map(world);
my_map.async_insert("one", 1);
world.barrier();
my_map.async_visit("one", [](const auto &key, auto &val, int &to_add) {
   val += to_add;
   }, world.size())
world.barrier();
will result in a value of world.size() * world.size() + 1 associated to the key "one".

Template Parameters:

  • Visitor – Type of user-provided function

  • VisitorArgs... – Variadic argument types to give to user function

Parameters:

  • key – Key to visit in container

  • visitor – User-provided function to execute at key

  • args... – Variadic arguments to pass to user-provided function

inline void async_visit_if_contains(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key, Visitor visitor, const VisitorArgs&... args)

Asynchronously visit key within a container and execute a user-provided function only if the key already exists.

This function differs from async_visit in that it will not default construct a value within the container prior to visiting a key that does not already exist.

Template Parameters:

  • Visitor – Type of user-provided function

  • VisitorArgs... – Variadic argument types to give to user function

Parameters:

  • key – Key to visit in container

  • visitor – User-provided function to execute at key

  • args... – Variadic arguments to pass to user-provided function

inline void async_visit_if_contains(const typename std::tuple_element<0, std::tuple<Key, Value>>::type &key, Visitor visitor, const VisitorArgs&... args) const

Version of async_visit_if_contains that works on const objects and provides const arguments to the user-provided lambda.

inline auto begin()

Returns an iterator to the beginning of the local container’s data.

This function is primarly a convienience function for range based for loops

Warning

The iterator is a local iterator, not a global iterator

Returns:

iterator to the beginning of the local container’s data.

inline auto begin() const

Returns a const_iterator to the beginning of the local container’s data.

This function is primarly a convienience function for range based for loops

Warning

The const_iterator is a local iterator, not a global iterator

Returns:

auto const_iterator to the beginning of the local container’s data.

inline auto cbegin() const

Returns a const_iterator to the beginning of the local container’s data.

This function is primarly a convienience function for range based for loops

Warning

The const_iterator is a local iterator, not a global iterator

Returns:

auto const_iterator to the beginning of the local container’s data.

inline auto end()

Returns an iterator to the end of the local container’s data.

This function is primarly a convienience function for range based for loops

Warning

The iterator is a local iterator, not a global iterator

Returns:

iterator to the end of the local container’s data.

inline auto end() const

Returns a const_iterator to the end of the local container’s data.

This function is primarly a convienience function for range based for loops

Warning

The const_iterator is a local iterator, not a global iterator

Returns:

auto const_iterator to the end of the local container’s data.

inline auto cend() const

Returns a const_iterator to the end of the local container’s data.

This function is primarly a convienience function for range based for loops

Warning

The const_iterator is a local iterator, not a global iterator

Returns:

auto const_iterator to the end of the local container’s data.

inline void for_all(Function fn)

Iterates over all items in a container and executes a user-provided function object on each.

The user-provided function is expected to take a single key and value as separate arguments that make a (key, value) pair within the container. If the user provides a lambda as their function object, the lambda is allowed to capture.

Template Parameters:

Function – Type of user-provided function

Parameters:

fn – User-provided function

inline void for_all(Function &&fn) const

Const version of for_all that iterates over all items and passes them to the user function as const *.

The user-provided function is expected to take a single key and value as separate arguments that make a (key, value) pair within the container. If the user provides a lambda as their function object, the lambda is allowed to capture.

Template Parameters:

Function – Type of user-provided function

Parameters:

fn – User-provided function

inline void gather(STLContainer &gto, int rank) const

Gather all values in an STL container.

Requires STL container to have a value_type that is (key, value) pairs from the YGM container

Template Parameters:

STLContainer – Type of STL container to gather to

Parameters:

  • gto – Container to store results in

  • rank – Rank to tather results on. Use -1 to gather to all ranks

inline void gather(STLContainer &gto) const

Gather all values in an STL container on all ranks.

Equivalent to gather(gto, -1)

Template Parameters:

STLContainer – Type of STL container to gather to

Parameters:

gto – Container to store results in

inline std::vector<std::pair<key_type, mapped_type>> gather_topk(size_t k, Compare comp = Compare()) const

Gather the k “largest” key-value pairs according to provided comparison function.

Template Parameters:

Compare – Type of comparison operator

Parameters:

  • k – Number of key-value pairs to gather

  • comp – Comparison function for identifying elements to gather

Returns:

vector of largest key-value pairs

inline void collect(YGMContainer &c) const

Collects all items in a new YGM container.

Template Parameters:

YGMContainer – Container type

Parameters:

c – Container to collect into

inline void reduce_by_key(MapType &map, ReductionOp reducer) const

Reduces all values in key-value pairs with matching keys.

Template Parameters:

  • MapType – Result YGM container type

  • ReductionOp – Functor type

Parameters:

  • map – YGM container to hold result

  • reducer – Functor for combining values

transform_proxy_key_value<map<Key, Value>, TransformFunction> transform(TransformFunction &&ffn)

Creates proxy that transforms key-value pairs in a container that are presented to user for_all calls.

The underlying items within the container are not modified.

Template Parameters:

TransformFunction – functor type

Parameters:

ffn – Function to transform items in container

inline auto keys()

Access to container presenting only keys.

Returns:

Transform object that returns only keys to user

inline auto values()

Access to container presenting only values.

Returns:

Transform object that returns only values to user

inline flatten_proxy_key_value<map<Key, Value>> flatten()

Flattens STL containers of values to allow a function to be called on inner items individually.

Underlying container is not modified.

filter_proxy_key_value<map<Key, Value>, FilterFunction> filter(FilterFunction &&ffn)

Filters items in a container so only allow for_all to execute on those that satisfy a given predicate function.

Filtered items are not removed from underlying container.

Template Parameters:

FilterFunction – Functor type

Parameters:

ffn – Function used to filter items in container.

Public Members

detail::hash_partitioner<detail::hash<key_type>> partitioner

Friends

friend struct detail::base_misc< map< Key, Value >, std::tuple< Key, Value > >