diff --git a/libs/core/algorithms/include/hpx/parallel/algorithms/uninitialized_relocate.hpp b/libs/core/algorithms/include/hpx/parallel/algorithms/uninitialized_relocate.hpp index 3be0d25038f0..c8d1d93bb7bb 100644 --- a/libs/core/algorithms/include/hpx/parallel/algorithms/uninitialized_relocate.hpp +++ b/libs/core/algorithms/include/hpx/parallel/algorithms/uninitialized_relocate.hpp @@ -63,7 +63,7 @@ namespace hpx { template FwdIter uninitialized_relocate(InIter1 first, InIter2 last, FwdIter dest); - /// Relocates the elements in the range defined by [first, first + count), to an + /// Relocates the elements in the range defined by [first, last), to an /// uninitialized memory area beginning at \a dest. If an exception is /// thrown during the move-construction of an element, all elements left /// in the input range, as well as all objects already constructed in the @@ -135,6 +135,125 @@ namespace hpx { uninitialized_relocate( ExPolicy&& policy, InIter1 first, InIter2 last, FwdIter dest); + /// Relocates the elements in the range, defined by [first, last), to an + /// uninitialized memory area ending at \a dest_last. The objects are + /// processed in reverse order. If an exception is thrown during the + /// the move-construction of an element, all elements left in the + /// input range, as well as all objects already constructed in the + /// destination range are destroyed. After this algorithm completes, the + /// source range should be freed or reused without destroying the objects. + /// + /// \note Complexity: time: O(n), space: O(1) + /// 1) For "trivially relocatable" underlying types (T) and + /// a contiguous iterator range [first, last): + /// std::distance(first, last)*sizeof(T) bytes are copied. + /// 2) For "trivially relocatable" underlying types (T) and + /// a non-contiguous iterator range [first, last): + /// std::distance(first, last) memory copies of sizeof(T) + /// bytes each are performed. + /// 3) For "non-trivially relocatable" underlying types (T): + /// std::distance(first, last) move assignments and + /// destructions are performed. + /// + /// \note Declare a type as "trivially relocatable" using the + /// `HPX_DECLARE_TRIVIALLY_RELOCATABLE` macros found in + /// . + /// + /// \tparam BiIter1 The type of the source range (deduced). + /// This iterator type must meet the requirements of a + /// Bidirectional iterator. + /// \tparam BiIter2 The type of the iterator representing the + /// destination range (deduced). + /// This iterator type must meet the requirements of a + /// Bidirectional iterator. + /// + /// \param first Refers to the beginning of the sequence of elements + /// the algorithm will be applied to. + /// \param last Refers to the end of the sequence of elements the + /// algorithm will be applied to. + /// \param dest_last Refers to the beginning of the destination range. + /// + /// The assignments in the parallel \a uninitialized_relocate algorithm invoked + /// without an execution policy object will execute in sequential order in + /// the calling thread. + /// + /// \returns The \a uninitialized_relocate_backward algorithm returns \a BiIter2. + /// The \a uninitialized_relocate_backward algorithm returns the + /// bidirectional iterator to the first element in the destination range. + /// + template + BiIter2 uninitialized_relocate_backward(BiIter1 first, BiIter1 last, + BiIter2 dest_last); + + /// Relocates the elements in the range, defined by [first, last), to an + /// uninitialized memory area ending at \a dest_last. The order of the + /// relocation of the objects depends on the execution policy. If an + /// exception is thrown during the the move-construction of an element, + /// all elements left in the input range, as well as all objects already + /// constructed in the destination range are destroyed. After this algorithm + /// completes, the source range should be freed or reused without destroying + /// the objects. + /// + /// \note Using the \a uninitialized_relocate_backward algorithm with the + /// with a non-sequenced execution policy, will not guarantee the + /// order of the relocation of the objects. + /// + /// \note Complexity: time: O(n), space: O(1) + /// 1) For "trivially relocatable" underlying types (T) and + /// a contiguous iterator range [first, last): + /// std::distance(first, last)*sizeof(T) bytes are copied. + /// 2) For "trivially relocatable" underlying types (T) and + /// a non-contiguous iterator range [first, last): + /// std::distance(first, last) memory copies of sizeof(T) + /// bytes each are performed. + /// 3) For "non-trivially relocatable" underlying types (T): + /// std::distance(first, last) move assignments and + /// destructions are performed. + /// + /// \note Declare a type as "trivially relocatable" using the + /// `HPX_DECLARE_TRIVIALLY_RELOCATABLE` macros found in + /// . + /// + /// \tparam ExPolicy The type of the execution policy to use (deduced). + /// It describes the manner in which the execution + /// of the algorithm may be parallelized and the manner + /// in which it executes the assignments. + /// \tparam BiIter1 The type of the source range (deduced). + /// This iterator type must meet the requirements of a + /// Bidirectional iterator. + /// \tparam BiIter2 The type of the iterator representing the + /// destination range (deduced). + /// This iterator type must meet the requirements of a + /// Bidirectional iterator. + /// + /// \param policy The execution policy to use for the scheduling of + /// the iterations. + /// \param first Refers to the beginning of the sequence of elements + /// the algorithm will be applied to. + /// \param last Refers to the end of the sequence of elements the + /// algorithm will be applied to. + /// \param dest_last Refers to the end of the destination range. + /// + /// The assignments in the parallel \a uninitialized_relocate_backward algorithm invoked + /// with an execution policy object of type \a parallel_policy or + /// \a parallel_task_policy are permitted to execute in an + /// unordered fashion in unspecified threads, and indeterminately sequenced + /// within each thread. + /// + /// \returns The \a uninitialized_relocate_backward algorithm returns a + /// \a hpx::future, if the execution policy is of type + /// \a sequenced_task_policy or + /// \a parallel_task_policy and + /// returns \a BiIter2 otherwise. + /// The \a uninitialized_relocate_backward algorithm returns the + /// bidirectional iterator to the first element in the destination + /// range. + /// + template + hpx::parallel::util::detail::algorithm_result + uninitialized_relocate_backward( + ExPolicy&& policy, BiIter1 first, BiIter1 last, BiIter2 dest_last); + /// Relocates the elements in the range, defined by [first, last), to an /// uninitialized memory area beginning at \a dest. If an exception is /// thrown during the move-construction of an element, all elements left