Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: fix & improve parallel algorithms documentation 2 #5939

Merged
merged 10 commits into from
Jul 13, 2022
Merged

docs: fix & improve parallel algorithms documentation 2 #5939

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
35cd136
docs: fix hpx::equal docs
bhumitattarde Jun 30, 2022
66d03e0
docs: fix hpx::exclusive_scan docs
bhumitattarde Jun 30, 2022
c8fb09f
docs: fix & add hpx::fill docs
bhumitattarde Jun 30, 2022
790c2a9
docs: fix & add hpx::find docs
bhumitattarde Jun 30, 2022
3e6b65d
docs: fix hpx::for_each docs
bhumitattarde Jun 30, 2022
e58580c
docs: ignore deprecated elements
bhumitattarde Jun 30, 2022
c4c904b
docs: fix for_loop_reduction docs
bhumitattarde Jun 30, 2022
b3b3417
docs: improve hpx::for_loop docs
bhumitattarde Jun 30, 2022
f342012
docs: improve hpx::count docs
bhumitattarde Jun 30, 2022
6ff9e0f
docs: fix wrong docs for hpx::count
bhumitattarde Jul 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 84 additions & 36 deletions libs/core/algorithms/include/hpx/parallel/algorithms/count.hpp
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the rationale for this change?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here, Op is the fourth template parameter and T is fifth. Am I missing something?

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
Open in desktop
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