bag

template<typename Item>
class bag : public ygm::container::detail::base_async_insert_value<bag<Item>, std::tuple<Item>>, public ygm::container::detail::base_contains<bag<Item>, std::tuple<Item>>, public ygm::container::detail::base_count<bag<Item>, std::tuple<Item>>, public ygm::container::detail::base_misc<bag<Item>, std::tuple<Item>>, public ygm::container::detail::base_iterators<bag<Item>>, public ygm::container::detail::base_iteration_value<bag<Item>, std::tuple<Item>>

Container that partitions elements across ranks for iteration.

Assigns items in a cyclic distribution from every rank independently

Public Types

using self_type = bag<Item>

using value_type = Item

using size_type = size_t

using for_all_args = std::tuple<Item>

using container_type = ygm::container::bag_tag

using iterator = typename local_container_type::iterator

using const_iterator = typename local_container_type::const_iterator

Public Functions

inline bag(ygm::comm &comm)

Bag construction from ygm::comm.

Parameters:

comm – Communicator to use for communication

inline bag(ygm::comm &comm, std::initializer_list<Item> l)

Bag constructor from std::initializer_list of values.

Initializer list is assumed to be replicated on all ranks.

Parameters:

• comm – Communicator to use for communication

• l – Initializer list of values to put in bag

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

Construct bag from existing STL container.

Template Parameters:

STLContainer – Existing container type

Parameters:

• comm – Communicator to use for communication

• cont – STL container containing values to put in bag

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

Construct bag from existing YGM container.

Requires container’s for_all_args to be a single item tuple to put in the bag

Template Parameters:

YGMContainer – Existing container type

Parameters:

• comm – Communicator to use for communication

• yc – YGM container of values to put in bag

inline ~bag()

inline bag(const self_type &other)

inline bag(self_type &&other) noexcept

inline bag &operator=(const self_type &other)

inline bag &operator=(self_type &&other) noexcept

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 bag.

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 bag.

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 end of items held by process.

inline const_iterator local_end() const

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

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 bag.

Does not call barrier().

Returns:

Local const iterator to ending of items held by process.

inline void async_insert(const Item &value, int dest)

Asynchronously insert an item on a specific rank.

Parameters:

• value – Value to insert in bag

• dest – Rank to insert item at

inline void async_insert(const std::vector<Item> &values, int dest)

Asynchronously insert multiple items on a specific rank.

Parameters:

• values – Vector of values to insert in bag

• dest – Rank to insert items at

inline void local_insert(const Item &val)

Insert an item into local storage.

Parameters:

val – Value to insert locally

inline void local_clear()

Clear the local storage of the bag.

inline size_t local_size() const

Get the number of items held locally.

Returns:

Number of locally-held items

inline size_t local_count(const value_type &val) const

Count the number of items held locally that match a query item.

Parameters:

val – Value to search for locally

Returns:

Number of locally-held copies of val

inline bool local_contains(const value_type &val) const

Check if a value exists locally.

Parameters:

val – Value to check for

Returns:

True if value exists locally, false otherwise

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

Execute a functor on every locally-held item.

Template Parameters:

Function – functor type

Parameters:

fn – Functor to execute on items

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

Execute a functor on a const version of every locally-held item.

Template Parameters:

Function – functor type

Parameters:

fn – Functor to execute on items

inline void serialize(const std::string &fname)

Serialize a bag to a collection of files to be read back in later.

Parameters:

fname – Filename prefix to create filename used by every rank from

inline void deserialize(const std::string &fname)

Deserialize a bag from files.

Currently requires the number of ranks deserializing a bag to be the same as was used for serialization.

Parameters:

fname – Filename prefix to create filename used by every rank from

inline void rebalance()

Repartition data to hold approximately equal numbers of items on every rank.

template<typename RandomFunc>
inline void local_shuffle(RandomFunc &r)

Shuffle elements held locally.

Template Parameters:

RandomFunc – Random number generator type

Parameters:

r – Random number generator

inline void local_shuffle()

Shuffle elements held locally with a default random number generator.

template<typename RandomFunc>
inline void global_shuffle(RandomFunc &r)

Shuffle elements of bag across ranks.

Template Parameters:

RandomFunc – Random number generator type

Parameters:

r – Random number generator

inline void global_shuffle()

Shuffle elements of bag across ranks with a default random number generator.

inline void async_insert(const typename std::tuple_element<0, std::tuple<Item>>::type &value)

Asynchronously inserts a value in a container.

ygm::container::bag<int> my_bag(world);
my_bag.async_insert(world.rank());

Parameters:

value – Value to insert into container

inline bool contains(const typename std::tuple_element<0, std::tuple<Item>>::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<Item>>::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 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(bag<Item> &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<bag<Item>> 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<bag<Item>> get_ygm_ptr() const

Const access to the ygm ptr used by the container.

Returns:

ygm_ptr to const version of container

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 argument that is an item 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 argument that is an item 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.

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<value_type> gather_topk(size_t k, Compare comp = std::greater<value_type>()) const

Gather the k “largest” values according to provided comparison function.

Template Parameters:

Compare – Type of comparison operator

Parameters:

• k – Number of values to gather

• comp – Comparison function for identifying elements to gather

Returns:

vector of largest values

inline value_type reduce(MergeFunction merge) const

Perform a reduction over all items in container.

reduce only makes sense to use with commutative and associative functors defining merges. Otherwise, ranks will not receive the same result.

Template Parameters:

MergeFunction – Merge functor type

Parameters:

merge – Functor to combine pairs of items

Returns:

Value from all reductions

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_value<bag<Item>, TransformFunction> transform(TransformFunction &&ffn)

Creates proxy that transforms items in container that are presented to user for_all calls.

The underlying items within the container are not modified.

ygm::container::bag<int> my_bag(world);
my_bag.async_insert(2);
my_bag.barrier();

my_bag.transform([](auto &val) { return 2*val; }).for_all([](const auto
&transformed_val) { YGM_ASSERT_RELEASE(val == 4);
});

my_bag.for_all([](const auto &val) { YGM_ASSERT_RELEASE(val == 2); });

will complete successfully.

Template Parameters:

TransformFunction – functor type

Parameters:

ffn – Function to transform items in container

inline flatten_proxy_value<bag<Item>> flatten()

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

Underlying container is not modified.

ygm::container::bag<std::vector<int>> my_bag(world, {{1, 2, 3}});

my_bag.flatten().for_all([](const int &nested_val) {
std::cout << "Nested value: " << nested_val << std::cout;
});

will print

Nested value: 1
Nested value: 2
Nested value: 3

filter_proxy_value<bag<Item>, 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.

ygm::container::bag<int> my_bag(world, {1, 2, 3, 4});
my_bag.filter([](const auto &val) { return (val % 2) == 0;
}).for_all([](const auto &filtered_val) { YGM_ASSERT_RELEASE((filtered_val %
2) == 0);
});

Template Parameters:

FilterFunction – Functor type

Parameters:

ffn – Function used to filter items in container.

Public Members

detail::round_robin_partitioner partitioner

Friends

friend struct detail::base_misc< bag< Item >, std::tuple< Item > >