Skip to content

Commit

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



Co-authored-by: Bhumit Attarde <bhumit.attarde01@gmail.com>
  • Loading branch information
@bhumitattarde
StellarBot and bhumitattarde committed Jul 13, 2022
2 parents 86e232a + 6ff9e0f commit d0dbb41
Show file tree
Hide file tree
Showing 9 changed files with 626 additions and 115 deletions.
120 changes: 84 additions & 36 deletions libs/core/algorithms/include/hpx/parallel/algorithms/count.hpp
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Copyright (c) 2022 Bhumit Attarde
// Copyright (c) 2014 Grant Mercer
// Copyright (c) 2020-2022 Hartmut Kaiser
//
Expand All @@ -15,23 +16,18 @@ namespace hpx {

/// Returns the number of elements in the range [first, last) satisfying
/// a specific criteria. This version counts the elements that are equal to
/// the given \a value.
/// the given \a value. Executed according to the policy.
///
/// \note Complexity: Performs exactly \a last - \a first comparisons.
///
/// \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 comparisons.
/// \tparam FwdIterB The type of the source begin iterator used (deduced).
/// This iterator type must meet the requirements of an
/// forward iterator.
/// \tparam FwdIterE The type of the source end iterator used (deduced).
/// \tparam FwdIter The type of the source iterator used (deduced).
/// This iterator type must meet the requirements of an
/// forward iterator.
/// \tparam T The type of the value to search for (deduced).
/// \tparam Proj The type of an optional projection function. This
/// defaults to \a util::projection_identity
///
/// \param policy The execution policy to use for the scheduling of
/// the iterations.
Expand All @@ -40,10 +36,6 @@ namespace hpx {
/// \param last Refers to the end of the sequence of elements the
/// algorithm will be applied to.
/// \param value The value to search for.
/// \param proj Specifies the function (or function object) which
/// will be invoked for each of the elements as a
/// projection operation before the actual predicate
/// \a is invoked.
///
/// The comparisons in the parallel \a count algorithm invoked with
/// an execution policy object of type \a sequenced_policy
Expand All @@ -64,17 +56,40 @@ namespace hpx {
/// is defined by \a std::iterator_traits<FwdIterB>::difference_type.
/// The \a count algorithm returns the number of elements
/// satisfying the given criteria.
///
template <typename ExPolicy, typename FwdIterB, typename FwdIterE,
typename T, typename Proj = util::projection_identity>
template <typename ExPolicy, typename FwdIter, typename T>
typename util::detail::algorithm_result<ExPolicy,
typename std::iterator_traits<FwdIterB>::difference_type>::type
count(ExPolicy&& policy, FwdIterB first, FwdIterE last, T const& value,
Proj&& proj = Proj());

typename std::iterator_traits<FwdIter>::difference_type>::type
count(ExPolicy&& policy, FwdIter first, FwdIter last, T const& value);

/// Returns the number of elements in the range [first, last) satisfying
/// a specific criteria. This version counts the elements that are equal to
/// the given \a value.
///
/// \note Complexity: Performs exactly \a last - \a first comparisons.
/// \tparam InIter The type of the source iterator used (deduced).
/// This iterator type must meet the requirements of an
/// input iterator.
/// \tparam T The type of the value to search for (deduced).
///
/// \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 value The value to search for.
///
///
/// \returns The \a count algorithm returns a \a difference_type (where \a difference_type
/// is defined by \a std::iterator_traits<InIter>::difference_type.
/// The \a count algorithm returns the number of elements
/// satisfying the given criteria.
///
template <typename InIter, typename T>
typename std::iterator_traits<InIter>::difference_type
count(InIter first, InIter last, T const& value);

/// Returns the number of elements in the range [first, last) satisfying
/// a specific criteria. This version counts elements for which predicate
/// \a f returns true.
/// \a f returns true. Executed according to the policy.
///
/// \note Complexity: Performs exactly \a last - \a first applications of
/// the predicate.
Expand All @@ -83,18 +98,13 @@ namespace hpx {
/// It describes the manner in which the execution
/// of the algorithm may be parallelized and the manner
/// in which it executes the comparisons.
/// \tparam Iter The type of the source begin iterator used (deduced).
/// This iterator type must meet the requirements of an
/// forward iterator.
/// \tparam Sent The type of the source end iterator used (deduced).
/// \tparam FwdIter The type of the source begin iterator used (deduced).
/// This iterator type must meet the requirements of an
/// forward iterator.
/// \tparam F The type of the function/function object to use
/// (deduced). Unlike its sequential form, the parallel
/// overload of \a count_if requires \a F to meet the
/// requirements of \a CopyConstructible.
/// \tparam Proj The type of an optional projection function. This
/// defaults to \a util::projection_identity
///
/// \param policy The execution policy to use for the scheduling of
/// the iterations.
Expand All @@ -114,12 +124,8 @@ namespace hpx {
/// The signature does not need to have const&, but
/// the function must not modify the objects passed to
/// it. The type \a Type must be such that an object of
/// type \a FwdIterB can be dereferenced and then
/// type \a FwdIter can be dereferenced and then
/// implicitly converted to Type.
/// \param proj Specifies the function (or function object) which
/// will be invoked for each of the elements as a
/// projection operation before the actual predicate
/// \a is invoked.
///
/// \note The assignments in the parallel \a count_if algorithm invoked with
/// an execution policy object of type \a sequenced_policy
Expand All @@ -136,16 +142,58 @@ namespace hpx {
/// \a sequenced_task_policy or
/// \a parallel_task_policy and
/// returns \a difference_type otherwise (where \a difference_type
/// is defined by \a std::iterator_traits<FwdIterB>::difference_type.
/// is defined by \a std::iterator_traits<FwdIter>::difference_type.
/// The \a count algorithm returns the number of elements
/// satisfying the given criteria.
///
template <typename ExPolicy, typename Iter, typename Sent,
typename F, typename Proj = util::projection_identity>
template <typename ExPolicy, typename FwdIter, typename F>
typename util::detail::algorithm_result<ExPolicy,
typename std::iterator_traits<Iter>::difference_type>::type
count_if(ExPolicy&& policy, Iter first, Sent last, F&& f,
Proj&& proj = Proj());
typename std::iterator_traits<FwdIter>::difference_type>::type
count_if(ExPolicy&& policy, FwdIter first, FwdIter last, F&& f);

/// Returns the number of elements in the range [first, last) satisfying
/// a specific criteria. This version counts elements for which predicate
/// \a f returns true.
///
/// \note Complexity: Performs exactly \a last - \a first applications of
/// the predicate.
///
/// \tparam InIter The type of the source begin iterator used (deduced).
/// This iterator type must meet the requirements of an
/// input iterator.
/// \tparam F The type of the function/function object to use
/// (deduced). Unlike its sequential form, the parallel
/// overload of \a count_if 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 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 which returns \a true for the
/// required elements. The signature of this predicate
/// should be equivalent to:
/// \code
/// bool pred(const Type &a);
/// \endcode \n
/// The signature does not need to have const&, but
/// the function must not modify the objects passed to
/// it. The type \a Type must be such that an object of
/// type \a InIter can be dereferenced and then
/// implicitly converted to Type.
///
/// \returns The \a count_if algorithm returns \a difference_type (where
/// a difference_type is defined by
/// \a std::iterator_traits<InIter>::difference_type.
/// The \a count algorithm returns the number of elements
/// satisfying the given criteria.
///
template <typename InIter, typename F>
typename std::iterator_traits<InIter>::difference_type
count_if(InIter first, InIter last, F&& f);

// clang-format on
} // namespace hpx
Expand Down
22 changes: 11 additions & 11 deletions libs/core/algorithms/include/hpx/parallel/algorithms/equal.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ namespace hpx {
/// [first2, last2), and false otherwise. Executed according to the
/// policy.
///
/// \note Complexity: At most min(last1 - first1, last2 - first2)
/// applications of the predicate \a f.
/// \note Complexity: O(min(\a last1 - \a first1, \a last2 - \a first2))
/// applications of the predicate \a op.
///
/// \tparam ExPolicy The type of the execution policy to use (deduced).
/// It describes the manner in which the execution
Expand Down Expand Up @@ -96,8 +96,8 @@ namespace hpx {
/// Returns true if the range [first1, last1) is equal to the range
/// [first2, last2), and false otherwise. Executed according to policy.
///
/// \note Complexity: At most min(last1 - first1, last2 - first2)
/// applications of the predicate \a f.
/// \note Complexity: O(min(\a last1 - \a first1, \a last2 - \a first2))
/// applications of the predicate \a std::equal_to.
///
/// \tparam ExPolicy The type of the execution policy to use (deduced).
/// It describes the manner in which the execution
Expand Down Expand Up @@ -156,8 +156,8 @@ namespace hpx {
/// Returns true if the range [first1, last1) is equal to the range
/// starting at first2, and false otherwise. Executed according to policy.
///
/// \note Complexity: At most \a last1 - \a first1 applications of the
/// predicate \a f.
/// \note Complexity: O(min(\a last1 - \a first1, \a last2 - \a first2))
/// applications of the predicate \a op.
///
/// \tparam ExPolicy The type of the execution policy to use (deduced).
/// It describes the manner in which the execution
Expand Down Expand Up @@ -232,7 +232,7 @@ namespace hpx {
/// [first2, last2), and false otherwise. Executed according to policy.
///
/// \note Complexity: At most \a last1 - \a first1 applications of the
/// predicate \a f.
/// predicate \a op.
///
/// \tparam ExPolicy The type of the execution policy to use (deduced).
/// It describes the manner in which the execution
Expand Down Expand Up @@ -290,7 +290,7 @@ namespace hpx {
/// [first2, last2), and false otherwise.
///
/// \note Complexity: At most min(last1 - first1, last2 - first2)
/// applications of the predicate \a f.
/// applications of the predicate \a op.
///
/// \tparam FwdIter1 The type of the source iterators used for the
/// first range (deduced).
Expand Down Expand Up @@ -348,7 +348,7 @@ namespace hpx {
/// [first2, last2), and false otherwise.
///
/// \note Complexity: At most min(last1 - first1, last2 - first2)
/// applications of the predicate \a f.
/// applications of the predicate \a std::equal_to.
///
/// \tparam FwdIter1 The type of the source iterators used for the
/// first range (deduced).
Expand Down Expand Up @@ -385,8 +385,8 @@ namespace hpx {
/// Returns true if the range [first1, last1) is equal to the range
/// [first2, first2 + (last1 - first1)), and false otherwise.
///
/// \note Complexity: At most min(last1 - first1, last2 - first2)
/// applications of the predicate \a f.
/// \note Complexity: At most \a last1 - \a first1 applications of the
/// predicate \a op.
///
/// \tparam FwdIter1 The type of the source iterators used for the
/// first range (deduced).
Expand Down
6 changes: 3 additions & 3 deletions libs/core/algorithms/include/hpx/parallel/algorithms/exclusive_scan.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -215,10 +215,10 @@ namespace hpx {
/// destination range (deduced).
/// This iterator type must meet the requirements of an
/// forward iterator.
/// \tparam T The type of the value to be used as initial (and
/// intermediate) values (deduced).
/// \tparam Op The type of the binary function object used for
/// the reduction operation.
/// \tparam T The type of the value to be used as initial (and
/// intermediate) values (deduced).
///
/// \param policy The execution policy to use for the scheduling of
/// the iterations.
Expand Down Expand Up @@ -276,7 +276,7 @@ namespace hpx {
/// \a inclusive_scan may be non-deterministic.
///
template <typename ExPolicy, typename FwdIter1, typename FwdIter2,
typename T, typename Op>
typename Op, typename T>
typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type
exclusive_scan(ExPolicy&& policy, FwdIter1 first, FwdIter1 last,
FwdIter2 dest, T init, Op&& op);
Expand Down
53 changes: 50 additions & 3 deletions libs/core/algorithms/include/hpx/parallel/algorithms/fill.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ namespace hpx {
// clang-format off

/// Assigns the given value to the elements in the range [first, last).
/// Executed according to the policy.
///
/// \note Complexity: Performs exactly \a last - \a first assignments.
///
Expand Down Expand Up @@ -55,8 +56,30 @@ namespace hpx {
typename util::detail::algorithm_result<ExPolicy>::type
fill(ExPolicy&& policy, FwdIter first, FwdIter last, T value);

/// Assigns the given value to the elements in the range [first, last).
///
/// \note Complexity: Performs exactly \a last - \a first assignments.
///
/// \tparam FwdIter The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of an
/// forward iterator.
/// \tparam T The type of the value to be assigned (deduced).
///
/// \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 value The value to be assigned.
///
/// \returns The \a fill algorithm returns a \a void.
///
template <typename FwdIter, typename T>
void fill(FwdIter first, FwdIter last, T value);


/// Assigns the given value value to the first count elements in the range
/// beginning at first if count > 0. Does nothing otherwise.
/// beginning at first if count > 0. Does nothing otherwise. Executed
/// according to the policy.
///
/// \note Complexity: Performs exactly \a count assignments, for
/// count > 0.
Expand All @@ -66,8 +89,8 @@ namespace hpx {
/// of the algorithm may be parallelized and the manner
/// in which it executes the assignments.
/// \tparam FwdIter The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of an
/// output iterator.
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam Size The type of the argument specifying the number of
/// elements to apply \a f to.
/// \tparam T The type of the value to be assigned (deduced).
Expand Down Expand Up @@ -101,6 +124,30 @@ namespace hpx {
typename util::detail::algorithm_result<ExPolicy, FwdIter>::type
fill_n(ExPolicy&& policy, FwdIter first, Size count, T value);

/// Assigns the given value value to the first count elements in the range
/// beginning at first if count > 0. Does nothing otherwise.
///
/// \note Complexity: Performs exactly \a count assignments, for
/// count > 0.
///
/// \tparam FwdIter The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of a
/// forward iterator.
/// \tparam Size The type of the argument specifying the number of
/// elements to apply \a f to.
/// \tparam T The type of the value to be assigned (deduced).
///
/// \param first Refers to the beginning of the sequence of elements
/// the algorithm will be applied to.
/// \param count Refers to the number of elements starting at
/// \a first the algorithm will be applied to.
/// \param value The value to be assigned.
///
/// \returns The \a fill_n algorithm returns a \a FwdIter.
///
template <typename FwdIter, typename Size, typename T>
FwdIter fill_n(FwdIter first, Size count, T value);

// clang-format on
} // namespace hpx

Expand Down
Loading

0 comments on commit d0dbb41

Please sign in to comment.