Skip to content

Commit

Permalink
updated documentation for uninitialized_value_construct
Browse files Browse the repository at this point in the history
  • Loading branch information
@Jedi18
Jedi18 committed Jul 5, 2021
1 parent 53f5fce commit 1854607
Show file tree
Hide file tree
Showing 6 changed files with 173 additions and 258 deletions.
6 changes: 4 additions & 2 deletions docs/sphinx/api/public_api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -573,13 +573,15 @@ Functions
- :cpp:func:`hpx::parallel::v1::uninitialized_fill_n`
- :cpp:func:`hpx::uninitialized_move`
- :cpp:func:`hpx::uninitialized_move_n`
- :cpp:func:`hpx::parallel::v1::uninitialized_value_construct`
- :cpp:func:`hpx::parallel::v1::uninitialized_value_construct_n`
- :cpp:func:`hpx::uninitialized_value_construct`
- :cpp:func:`hpx::uninitialized_value_construct_n`

- :cpp:func:`hpx::ranges::uninitialized_default_construct`
- :cpp:func:`hpx::ranges::uninitialized_default_construct_n`
- :cpp:func:`hpx::ranges::uninitialized_move`
- :cpp:func:`hpx::ranges::uninitialized_move_n`
- :cpp:func:`hpx::ranges::uninitialized_value_construct`
- :cpp:func:`hpx::ranges::uninitialized_value_construct_n`

Header ``hpx/numeric.hpp``
==========================
Expand Down
4 changes: 2 additions & 2 deletions docs/sphinx/manual/writing_single_node_hpx_applications.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -748,11 +748,11 @@ Parallel algorithms
* Moves a number of objects to an uninitialized area of memory.
* ``<hpx/memory.hpp>``
* :cppreference-memory:`uninitialized_move_n`
* * :cpp:func:`hpx::parallel::v1::uninitialized_value_construct`
* * :cpp:func:`hpx::uninitialized_value_construct`
* Constructs objects in an uninitialized area of memory.
* ``<hpx/memory.hpp>``
* :cppreference-memory:`uninitialized_value_construct`
* * :cpp:func:`hpx::parallel::v1::uninitialized_value_construct_n`
* * :cpp:func:`hpx::uninitialized_value_construct_n`
* Constructs objects in an uninitialized area of memory.
* ``<hpx/memory.hpp>``
* :cppreference-memory:`uninitialized_value_construct_n`
Expand Down
221 changes: 66 additions & 155 deletions .../parallelism/algorithms/include/hpx/parallel/algorithms/uninitialized_value_construct.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,39 +10,40 @@

#if defined(DOXYGEN)
namespace hpx {
// clang-format off

/// Copies the given \a value to an uninitialized memory area, defined by
/// the range [first, last). If an exception is thrown during the
/// Constructs objects of type typename iterator_traits<ForwardIt>
/// ::value_type in the uninitialized storage designated by the range
/// by value-initialization. If an exception is thrown during the
/// initialization, the function has no effects.
///
/// \note Complexity: Linear in the distance between \a first and \a 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.
///
/// The assignments in the parallel \a uninitialized_default_construct algorithm invoked
/// without an execution policy object will execute in sequential order in
/// the calling thread.
/// The assignments in the parallel \a uninitialized_value_construct
/// algorithm invoked without an execution policy object will execute in
/// sequential order in the calling thread.
///
/// \returns The \a uninitialized_default_construct algorithm returns nothing
/// \returns The \a uninitialized_value_construct algorithm
/// returns nothing
///
template <typename FwdIter, typename T>
void uninitialized_default_construct(
FwdIter first, FwdIter last, T const& value);
template <typename FwdIter>
void uninitialized_value_construct(FwdIter first, FwdIter last);

/// Copies the given \a value to an uninitialized memory area, defined by
/// the range [first, last). If an exception is thrown during the
/// Constructs objects of type typename iterator_traits<ForwardIt>
/// ::value_type in the uninitialized storage designated by the range
/// by value-initialization. If an exception is thrown during the
/// initialization, the function has no effects.
///
/// \note Complexity: Linear in the distance between \a first and \a last
/// \note Complexity: Performs exactly \a last - \a first assignments.
///
/// \tparam ExPolicy The type of the execution policy to use (deduced).
/// It describes the manner in which the execution
Expand All @@ -51,75 +52,71 @@ namespace hpx {
/// \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 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 value The value to be assigned.
///
/// The initializations in the parallel \a uninitialized_default_construct algorithm
/// invoked with an execution policy object of type
/// \a sequenced_policy execute in sequential order in the
/// calling thread.
/// The assignments in the parallel \a uninitialized_value_construct
/// algorithm invoked with an execution policy object of type \a
/// sequenced_policy execute in sequential order in the calling thread.
///
/// The initializations in the parallel \a uninitialized_default_construct 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.
/// The assignments in the parallel \a uninitialized_value_construct
/// 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_default_construct algorithm returns a
/// \returns The \a uninitialized_value_construct algorithm returns a
/// \a hpx::future<void>, if the execution policy is of type
/// \a sequenced_task_policy or
/// \a parallel_task_policy and returns nothing
/// otherwise.
///
template <typename ExPolicy, typename FwdIter, typename T>
template <typename ExPolicy, typename FwdIter>
typename parallel::util::detail::algorithm_result<ExPolicy>::type
uninitialized_default_construct(
ExPolicy&& policy, FwdIter first, FwdIter last, T const& value);
uninitialized_value_construct(
ExPolicy&& policy, FwdIter first, FwdIter last);

/// Copies the given \a value value to the first count elements in an
/// uninitialized memory area beginning at first. If an exception is thrown
/// during the initialization, the function has no effects.
/// Constructs objects of type typename iterator_traits<ForwardIt>
/// ::value_type in the uninitialized storage designated by the range
/// [first, first + count) by value-initialization. If an exception
/// is thrown during the initialization, the function has no effects.
///
/// \note Complexity: Performs exactly \a count assignments, if
/// count > 0, no assignments otherwise.
///
/// \tparam FwdIter The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of a
/// This iterator type must meet the requirements of an
/// 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.
///
/// The assignments in the parallel \a uninitialized_default_construct_n algorithm
/// invoked without an execution policy object execute in sequential order
/// in the calling thread.
/// The assignments in the parallel \a uninitialized_value_construct_n
/// algorithm invoked without an execution policy object execute in
/// sequential order in the calling thread.
///
/// \returns The \a uninitialized_default_construct_n algorithm returns a
/// \returns The \a uninitialized_value_construct_n algorithm returns a
/// returns \a FwdIter.
/// The \a uninitialized_default_construct_n algorithm returns the output
/// iterator to the element in the range, one past
/// the last element copied.
/// The \a uninitialized_value_construct_n algorithm returns
/// the iterator to the element in the source range, one past
/// the last element constructed.
///
template <typename FwdIter, typename Size, typename T>
FwdIter uninitialized_default_construct_n(
FwdIter first, Size count, T const& value);
template <typename FwdIter, typename Size>
FwdIter uninitialized_value_construct_n(FwdIter first, Size count);

/// Copies the given \a value value to the first count elements in an
/// uninitialized memory area beginning at first. If an exception is thrown
/// during the initialization, the function has no effects.
/// Constructs objects of type typename iterator_traits<ForwardIt>
/// ::value_type in the uninitialized storage designated by the range
/// [first, first + count) by value-initialization. If an exception
/// is thrown during the initialization, the function has no effects.
///
/// \note Complexity: Performs exactly \a count assignments, if
/// count > 0, no assignments otherwise.
Expand All @@ -129,44 +126,44 @@ 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 a
/// This iterator type must meet the requirements of an
/// 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 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 count Refers to the number of elements starting at
/// \a first the algorithm will be applied to.
/// \param value The value to be assigned.
///
/// The initializations in the parallel \a uninitialized_default_construct_n algorithm
/// invoked with an execution policy object of type
/// The assignments in the parallel \a uninitialized_value_construct_n
/// algorithm invoked with an execution policy object of type
/// \a sequenced_policy execute in sequential order in the
/// calling thread.
///
/// The initializations in the parallel \a uninitialized_default_construct_n 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.
/// The assignments in the parallel \a uninitialized_value_construct_n
/// 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_default_construct_n algorithm returns a
/// \a hpx::future<FwdIter>, if the execution policy is of type
/// \returns The \a uninitialized_value_construct_n algorithm returns a
/// \a hpx::future<FwdIter> if the execution policy is of type
/// \a sequenced_task_policy or
/// \a parallel_task_policy and returns FwdIter
/// otherwise.
/// The \a uninitialized_default_construct_n algorithm returns the output
/// iterator to the element in the range, one past
/// the last element copied.
/// \a parallel_task_policy and
/// returns \a FwdIter otherwise.
/// The \a uninitialized_value_construct_n algorithm returns
/// the iterator to the element in the source range, one past
/// the last element constructed.
///
template <typename ExPolicy, typename FwdIter, typename Size, typename T>
template <typename ExPolicy, typename FwdIter, typename Size>
typename parallel::util::detail::algorithm_result<ExPolicy, FwdIter>::type
uninitialized_default_construct_n(
ExPolicy&& policy, FwdIter first, Size count, T const& value);
uninitialized_value_construct_n(
ExPolicy&& policy, FwdIter first, Size count);
// clang-format on
} // namespace hpx

#else // DOXYGEN
Expand Down Expand Up @@ -196,8 +193,6 @@ namespace hpx { namespace parallel { inline namespace v1 {
///////////////////////////////////////////////////////////////////////////
// uninitialized_value_construct
namespace detail {
/// \cond NOINTERNAL

// provide our own implementation of std::uninitialized_value_construct
// as some versions of MSVC horribly fail at compiling it for some types
// T
Expand Down Expand Up @@ -316,46 +311,8 @@ namespace hpx { namespace parallel { inline namespace v1 {
detail::distance(first, last));
}
};
/// \endcond
} // namespace detail

/// Constructs objects of type typename iterator_traits<ForwardIt>::value_type
/// in the uninitialized storage designated by the range [first, last) by
/// default-initialization. If an exception is thrown during the
/// initialization, the function has no effects.
///
/// \note Complexity: Performs exactly \a last - \a first assignments.
///
/// \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 FwdIter The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of an
/// forward 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.
///
/// The assignments in the parallel \a uninitialized_value_construct
/// algorithm invoked with an execution policy object of type \a sequenced_policy
/// execute in sequential order in the calling thread.
///
/// The assignments in the parallel \a uninitialized_value_construct
/// 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_value_construct algorithm returns a
/// \a hpx::future<void>, if the execution policy is of type
/// \a sequenced_task_policy or
/// \a parallel_task_policy and returns \a void otherwise.
///
template <typename ExPolicy, typename FwdIter,
HPX_CONCEPT_REQUIRES_(hpx::is_execution_policy<ExPolicy>::value&&
hpx::traits::is_iterator<FwdIter>::value)>
Expand Down Expand Up @@ -451,52 +408,6 @@ namespace hpx { namespace parallel { inline namespace v1 {
/// \endcond
} // namespace detail

/// Constructs objects of type typename iterator_traits<ForwardIt>::value_type
/// in the uninitialized storage designated by the range [first, first + count) by
/// default-initialization. If an exception is thrown during the
/// initialization, the function has no effects.
///
/// \note Complexity: Performs exactly \a count assignments, if
/// count > 0, no assignments otherwise.
///
/// \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 FwdIter The type of the source iterators used (deduced).
/// This iterator type must meet the requirements of an
/// forward iterator.
/// \tparam Size The type of the argument specifying the number of
/// elements to apply \a f to.
///
/// \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 count Refers to the number of elements starting at
/// \a first the algorithm will be applied to.
///
/// The assignments in the parallel \a uninitialized_value_construct_n
/// algorithm invoked with an execution policy object of type
/// \a sequenced_policy execute in sequential order in the
/// calling thread.
///
/// The assignments in the parallel \a uninitialized_value_construct_n
/// 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_value_construct_n algorithm returns a
/// \a hpx::future<FwdIter> if the execution policy is of type
/// \a sequenced_task_policy or
/// \a parallel_task_policy and
/// returns \a FwdIter otherwise.
/// The \a uninitialized_value_construct_n algorithm returns the
/// iterator to the element in the source range, one past
/// the last element constructed.
///
template <typename ExPolicy, typename FwdIter, typename Size,
HPX_CONCEPT_REQUIRES_(hpx::is_execution_policy<ExPolicy>::value&&
hpx::traits::is_iterator<FwdIter>::value)>
Expand Down
Loading

0 comments on commit 1854607

Please sign in to comment.