pack_traversal

The contents of this module can be included with the header hpx/modules/pack_traversal.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/pack_traversal.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx
namespace util

Functions

template<typename Mapper, typename... T><unspecified> hpx::util::map_pack(Mapper && mapper, T &&... pack)

Maps the pack with the given mapper.

This function tries to visit all plain elements which may be wrapped in:

  • homogeneous containers (std::vector, std::list)

  • heterogeneous containers (hpx::tuple, std::pair, std::array) and re-assembles the pack with the result of the mapper. Mapping from one type to a different one is supported.

Elements that aren’t accepted by the mapper are routed through and preserved through the hierarchy.

// Maps all integers to floats
map_pack([](int value) {
    return float(value);
},
1, hpx::make_tuple(2, std::vector<int>{3, 4}), 5);

Return

The mapped element or in case the pack contains multiple elements, the pack is wrapped into a hpx::tuple.

Exceptions

  • std::exception: like objects which are thrown by an invocation to the mapper.

Parameters

  • mapper: A callable object, which accept an arbitrary type and maps it to another type or the same one.

  • pack: An arbitrary variadic pack which may contain any type.

namespace hpx
namespace util

Functions

template<typename Visitor, typename ...T>
auto traverse_pack_async(Visitor &&visitor, T&&... pack)

Traverses the pack with the given visitor in an asynchronous way.

This function works in the same way as traverse_pack, however, we are able to suspend and continue the traversal at later time. Thus we require a visitor callable object which provides three operator() overloads as depicted by the code sample below: 

struct my_async_visitor
{
    template <typename T>
    bool operator()(async_traverse_visit_tag, T&& element)
    {
        return true;
    }

    template <typename T, typename N>
    void operator()(async_traverse_detach_tag, T&& element, N&& next)
    {
    }

    template <typename T>
    void operator()(async_traverse_complete_tag, T&& pack)
    {
    }
};

See

traverse_pack for a detailed description about the traversal behavior and capabilities.
Return

A hpx::intrusive_ptr that references an instance of the given visitor object.

Parameters

  • visitor: A visitor object which provides the three operator() overloads that were described above. Additionally the visitor must be compatible for referencing it from a hpx::intrusive_ptr. The visitor should must have a virtual destructor!

  • pack: The arbitrary parameter pack which is traversed asynchronously. Nested objects inside containers and tuple like types are traversed recursively.

template<typename Allocator, typename Visitor, typename ...T>
auto traverse_pack_async_allocator(Allocator const &alloc, Visitor &&visitor, T&&... pack)

Traverses the pack with the given visitor in an asynchronous way.

This function works in the same way as traverse_pack, however, we are able to suspend and continue the traversal at later time. Thus we require a visitor callable object which provides three operator() overloads as depicted by the code sample below: 

struct my_async_visitor
{
    template <typename T>
    bool operator()(async_traverse_visit_tag, T&& element)
    {
        return true;
    }

    template <typename T, typename N>
    void operator()(async_traverse_detach_tag, T&& element, N&& next)
    {
    }

    template <typename T>
    void operator()(async_traverse_complete_tag, T&& pack)
    {
    }
};

See

traverse_pack for a detailed description about the traversal behavior and capabilities.
Return

A hpx::intrusive_ptr that references an instance of the given visitor object.

Parameters

  • visitor: A visitor object which provides the three operator() overloads that were described above. Additionally the visitor must be compatible for referencing it from a hpx::intrusive_ptr. The visitor should must have a virtual destructor!

  • pack: The arbitrary parameter pack which is traversed asynchronously. Nested objects inside containers and tuple like types are traversed recursively.

  • alloc: Allocator instance to use to create the traversal frame.

namespace hpx

Functions

template<typename ...Args>
auto unwrap(Args&&... args)

A helper function for retrieving the actual result of any hpx::future like type which is wrapped in an arbitrary way.

Unwraps the given pack of arguments, so that any hpx::future object is replaced by its future result type in the argument pack:

  • hpx::future<int> -> int

  • hpx::future<std::vector<float>> -> std::vector<float>

  • std::vector<future<float>> -> std::vector<float>

The function is capable of unwrapping hpx::future like objects that are wrapped inside any container or tuple like type, see hpx::util::map_pack() for a detailed description about which surrounding types are supported. Non hpx::future like types are permitted as arguments and passed through.

// Single arguments
int i1 = hpx:unwrap(hpx::make_ready_future(0));

// Multiple arguments
hpx::tuple<int, int> i2 =
    hpx:unwrap(hpx::make_ready_future(1),
               hpx::make_ready_future(2));

Note

This function unwraps the given arguments until the first traversed nested hpx::future which corresponds to an unwrapping depth of one. See hpx::unwrap_n() for a function which unwraps the given arguments to a particular depth or hpx::unwrap_all() that unwraps all future like objects recursively which are contained in the arguments.

Return

Depending on the count of arguments this function returns a hpx::tuple containing the unwrapped arguments if multiple arguments are given. In case the function is called with a single argument, the argument is unwrapped and returned.

Parameters

  • args: the arguments that are unwrapped which may contain any arbitrary future or non future type.

Exceptions

  • std::exception: like objects in case any of the given wrapped hpx::future objects were resolved through an exception. See hpx::future::get() for details.

template<std::size_t Depth, typename ...Args>
auto unwrap_n(Args&&... args)

An alterntive version of hpx::unwrap(), which unwraps the given arguments to a certain depth of hpx::future like objects.

See unwrap for a detailed description.

Template Parameters

  • Depth: The count of hpx::future like objects which are unwrapped maximally.

template<typename ...Args>
auto unwrap_all(Args&&... args)

An alterntive version of hpx::unwrap(), which unwraps the given arguments recursively so that all contained hpx::future like objects are replaced by their actual value.

See hpx::unwrap() for a detailed description.

template<typename T>
auto unwrapping(T &&callable)

Returns a callable object which unwraps its arguments upon invocation using the hpx::unwrap() function and then passes the result to the given callable object.

auto callable = hpx::unwrapping([](int left, int right) {
    return left + right;
});

int i1 = callable(hpx::make_ready_future(1),
                  hpx::make_ready_future(2));

See hpx::unwrap() for a detailed description.

Parameters

  • callable: the callable object which which is called with the result of the corresponding unwrap function.

template<std::size_t Depth, typename T>
auto unwrapping_n(T &&callable)

Returns a callable object which unwraps its arguments upon invocation using the hpx::unwrap_n() function and then passes the result to the given callable object.

See hpx::unwrapping() for a detailed description.

template<typename T>
auto unwrapping_all(T &&callable)

Returns a callable object which unwraps its arguments upon invocation using the hpx::unwrap_all() function and then passes the result to the given callable object.

See hpx::unwrapping() for a detailed description.

namespace functional
struct unwrap
#include <unwrap.hpp>

A helper function object for functionally invoking hpx::unwrap. For more information please refer to its documentation.

struct unwrap_all
#include <unwrap.hpp>

A helper function object for functionally invoking hpx::unwrap_all. For more information please refer to its documentation.

template<std::size_t Depth>
struct unwrap_n
#include <unwrap.hpp>

A helper function object for functionally invoking hpx::unwrap_n. For more information please refer to its documentation.

namespace util

Functions

template<typename ...Args>
auto unwrap(Args&&... args)
template<std::size_t Depth, typename ...Args>
auto unwrap_n(Args&&... args)
template<typename ...Args>
auto unwrap_all(Args&&... args)
template<typename T>
auto unwrapping(T &&callable)
template<std::size_t Depth, typename T>
auto unwrapping_n(T &&callable)
template<typename T>
auto unwrapping_all(T &&callable)
namespace functional

Functions

struct hpx::util::functional::HPX_DEPRECATED_V(1, 7, "Please use  hpx::functional::unwrap  instead.")
template<typename NewType, typename OldType, typename OldAllocator>
struct pack_traversal_rebind_container<NewType, std::vector<OldType, OldAllocator>>

Public Types

template<>
using NewAllocator = typename std::allocator_traits<OldAllocator>::template rebind_alloc<NewType>

Public Static Functions

static std::vector<NewType, NewAllocator> call(std::vector<OldType, OldAllocator> const &container)
template<typename NewType, typename OldType, typename OldAllocator>
struct pack_traversal_rebind_container<NewType, std::list<OldType, OldAllocator>>

Public Types

template<>
using NewAllocator = typename std::allocator_traits<OldAllocator>::template rebind_alloc<NewType>

Public Static Functions

static std::list<NewType, NewAllocator> call(std::list<OldType, OldAllocator> const &container)
template<typename NewType, typename OldType, std::size_t N>
struct pack_traversal_rebind_container<NewType, std::array<OldType, N>>

Public Static Functions

static std::array<NewType, N> call(std::array<OldType, N> const&)
namespace hpx
namespace traits
template<typename NewType, typename OldType, std::size_t N>
struct pack_traversal_rebind_container<NewType, std::array<OldType, N>>

Public Static Functions

static std::array<NewType, N> call(std::array<OldType, N> const&)
template<typename NewType, typename OldType, typename OldAllocator>
struct pack_traversal_rebind_container<NewType, std::list<OldType, OldAllocator>>

Public Types

template<>
using NewAllocator = typename std::allocator_traits<OldAllocator>::template rebind_alloc<NewType>

Public Static Functions

static std::list<NewType, NewAllocator> call(std::list<OldType, OldAllocator> const &container)
template<typename NewType, typename OldType, typename OldAllocator>
struct pack_traversal_rebind_container<NewType, std::vector<OldType, OldAllocator>>

Public Types

template<>
using NewAllocator = typename std::allocator_traits<OldAllocator>::template rebind_alloc<NewType>

Public Static Functions

static std::vector<NewType, NewAllocator> call(std::vector<OldType, OldAllocator> const &container)