Skip to content

Commit

Permalink
Merge #5975
Browse files Browse the repository at this point in the history 
5975: docs: fix & improve parallel algorithms documentation 5 r=hkaiser a=bhumitattarde



Co-authored-by: Bhumit Attarde <[email protected]>
  • Loading branch information
@bhumitattarde
StellarBot and bhumitattarde committed Sep 4, 2022
2 parents 6563e90 + 5859600 commit c35e16b
Show file tree
Hide file tree
Showing 10 changed files with 524 additions and 572 deletions.
144 changes: 124 additions & 20 deletions libs/core/algorithms/include/hpx/parallel/algorithms/transform.hpp
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
// Copyright (c) 2007-2022 Hartmut Kaiser
// Copyright (c) 2021 Giannis Gonidelis
// Copyright (c) 2022 Bhumit Attarde
//
// SPDX-License-Identifier: BSL-1.0
// Distributed under the Boost Software License, Version 1.0. (See accompanying
Expand All @@ -17,16 +18,65 @@ namespace hpx {
///
/// \note Complexity: Exactly \a last - \a first applications of \a f
///
/// \tparam FwdIter1 The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam FwdIter2 The type of the iterator representing the
/// destination range (deduced).
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam F The type of the function/function object to use
/// (deduced). Unlike its sequential form, the parallel
/// overload of \a transform requires \a F to meet the
/// requirements of \a CopyConstructible.
///
/// \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 Refers to the beginning of the destination range.
/// \param f Specifies the function (or function object) which
/// will be invoked for each of the elements in the
/// sequence specified by [first, last).This is an
/// unary predicate. The signature of this predicate
/// should be equivalent to:
/// \code
/// Ret fun(const Type &a);
/// \endcode \n
/// The signature does not need to have const&.
/// The type \a Type must be such that an object of
/// type \a FwdIter1 can be dereferenced and then
/// implicitly converted to \a Type. The type \a Ret
/// must be such that an object of type \a FwdIter2 can
/// be dereferenced and assigned a value of type
/// \a Ret.
///
/// \returns The \a transform algorithm returns a \a FwdIter2.
/// The \a transform algorithm returns a tuple holding an iterator
/// referring to the first element after the input sequence and
/// the output iterator to the
/// element in the destination range, one past the last element
/// copied.
///
template <typename FwdIter1, typename FwdIter2, typename F>
FwdIter2 transform(FwdIter1 first, FwdIter1 last, FwdIter2 dest, F&& f);

/// Applies the given function \a f to the range [first, last) and stores
/// the result in another range, beginning at dest. Executed according to
/// the policy.
///
/// \note Complexity: Exactly \a last - \a first applications of \a f
///
/// \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 invocations of \a f.
/// \tparam FwdIter1 The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of an
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam FwdIter2 The type of the iterator representing the
/// destination range (deduced).
/// This iterator type must meet the requirements of an
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam F The type of the function/function object to use
/// (deduced). Unlike its sequential form, the parallel
Expand Down Expand Up @@ -67,10 +117,9 @@ namespace hpx {
/// within each thread.
///
/// \returns The \a transform algorithm returns a
/// \a hpx::future<in_out_result<FwdIter1, FwdIter2> >
/// \a hpx::future<FwdIter2>
/// if the execution policy is of type \a parallel_task_policy
/// and returns
/// \a in_out_result<FwdIter1, FwdIter2> otherwise.
/// and returns \a FwdIter2 otherwise.
/// The \a transform algorithm returns a tuple holding an iterator
/// referring to the first element after the input sequence and
/// the output iterator to the
Expand All @@ -79,9 +128,7 @@ namespace hpx {
///
template <typename ExPolicy, typename FwdIter1, typename FwdIter2,
typename F>
typename util::detail::algorithm_result<ExPolicy,
util::in_out_result<FwdIter1, FwdIter2>>::type
transform(
parallel::util::detail::algorithm_result_t<ExPolicy, FwdIter2> transform(
ExPolicy&& policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, F&& f);

/// Applies the given function \a f to pairs of elements from two ranges:
Expand All @@ -90,21 +137,82 @@ namespace hpx {
///
/// \note Complexity: Exactly \a last - \a first applications of \a f
///
/// \tparam FwdIter1 The type of the source iterators for the first
/// range used (deduced).
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam FwdIter2 The type of the source iterators for the second
/// range used (deduced).
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam FwdIter3 The type of the iterator representing the
/// destination range (deduced).
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam F The type of the function/function object to use
/// (deduced). Unlike its sequential form, the parallel
/// overload of \a transform requires \a F to meet the
/// requirements of \a CopyConstructible.
///
/// \param first1 Refers to the beginning of the first sequence of
/// elements the algorithm will be applied to.
/// \param last1 Refers to the end of the first sequence of elements
/// the algorithm will be applied to.
/// \param first2 Refers to the beginning of the second sequence of
/// elements the algorithm will be applied to.
/// \param dest Refers to the beginning of the destination range.
/// \param f Specifies the function (or function object) which
/// will be invoked for each of the elements in the
/// sequence specified by [first, last).This is a
/// binary predicate. The signature of this predicate
/// should be equivalent to:
/// \code
/// Ret fun(const Type1 &a, const Type2 &b);
/// \endcode \n
/// The signature does not need to have const&.
/// The types \a Type1 and \a Type2 must be such that
/// objects of types FwdIter1 and FwdIter2 can be
/// dereferenced and then implicitly converted to
/// \a Type1 and \a Type2 respectively. The type \a Ret
/// must be such that an object of type \a FwdIter3 can
/// be dereferenced and assigned a value of type
/// \a Ret.
///
/// \returns The \a transform algorithm returns a \a FwdIter3.
/// The \a transform algorithm returns a tuple holding an iterator
/// referring to the first element after the first input sequence,
/// an iterator referring to the first element after the second
/// input sequence, and the output iterator referring to the
/// element in the destination range, one past the last element
/// copied.
///
template <typename FwdIter1, typename FwdIter2, typename FwdIter3,
typename F>
FwdIter3 transform(
FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter3 dest, F&& f);

/// Applies the given function \a f to pairs of elements from two ranges:
/// one defined by [first1, last1) and the other beginning at first2, and
/// stores the result in another range, beginning at dest. Executed
/// according to the policy.
///
/// \note Complexity: Exactly \a last - \a first applications of \a f
///
/// \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 invocations of \a f.
/// \tparam FwdIter1 The type of the source iterators for the first
/// range used (deduced).
/// This iterator type must meet the requirements of an
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam FwdIter2 The type of the source iterators for the second
/// range used (deduced).
/// This iterator type must meet the requirements of an
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam FwdIter3 The type of the iterator representing the
/// destination range (deduced).
/// This iterator type must meet the requirements of an
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam F The type of the function/function object to use
/// (deduced). Unlike its sequential form, the parallel
Expand Down Expand Up @@ -147,12 +255,9 @@ namespace hpx {
/// fashion in unspecified threads, and indeterminately sequenced
/// within each thread.
///
/// \returns The \a transform algorithm returns a
/// \a hpx::future<in_in_out_result<FwdIter1, FwdIter2, FwdIter3> >
/// \returns The \a transform algorithm returns a \a hpx::future<FwdIter3>
/// if the execution policy is of type \a parallel_task_policy
/// and returns
/// \a in_in_out_result<FwdIter1, FwdIter2, FwdIter3>
/// otherwise.
/// and returns \a FwdIter3 otherwise.
/// The \a transform algorithm returns a tuple holding an iterator
/// referring to the first element after the first input sequence,
/// an iterator referring to the first element after the second
Expand All @@ -162,10 +267,9 @@ namespace hpx {
///
template <typename ExPolicy, typename FwdIter1, typename FwdIter2,
typename FwdIter3, typename F>
typename util::detail::algorithm_result<ExPolicy,
util::in_in_out_result<FwdIter1, FwdIter2, FwdIter3>>::type
transform(ExPolicy&& policy, FwdIter1 first1, FwdIter1 last1,
FwdIter2 first2, FwdIter3 dest, F&& f);
parallel::util::detail::algorithm_result_t<ExPolicy, FwdIter3> transform(
ExPolicy&& policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2,
FwdIter3 dest, F&& f);

} // namespace hpx

Expand Down
Loading

0 comments on commit c35e16b

Please sign in to comment.