From e0abd4b1a0a2db8f210e386c8fce36c518966f72 Mon Sep 17 00:00:00 2001 From: Joseph Schuchart Date: Wed, 29 Mar 2017 18:00:21 +0200 Subject: [PATCH 1/5] Add \example documentation --- dash/examples/ex.01.hello-mpi/main.cpp | 9 +++++++ dash/examples/ex.02.array-csr/main.cpp | 7 +++++ dash/examples/ex.02.array-delayed/main.cpp | 6 +++++ dash/examples/ex.03.globref/main.cpp | 6 +++++ dash/examples/ex.04.memalloc/main.cpp | 6 +++++ dash/examples/ex.05.min_element/main.cpp | 6 +++++ .../ex.06.pattern-block-visualizer/main.cpp | 6 +++++ .../ex.06.pattern-visualizer/main.cpp | 7 +++++ dash/examples/ex.06.std-algo/main.cpp | 6 +++++ dash/examples/ex.08.io-hdf5-stream/main.cpp | 8 ++++++ dash/examples/ex.08.io-hdf5/main.cpp | 7 +++++ dash/examples/ex.10.radixsort/main.cpp | 5 ++++ dash/examples/ex.11.simple-stencil/main.cpp | 2 +- dash/include/dash/Matrix.h | 26 +++++++++---------- dash/include/dash/Mutex.h | 4 +-- dash/include/dash/atomic/GlobAtomicRef.h | 4 +-- dash/include/dash/matrix/MatrixRef.h | 10 +++---- 17 files changed, 102 insertions(+), 23 deletions(-) diff --git a/dash/examples/ex.01.hello-mpi/main.cpp b/dash/examples/ex.01.hello-mpi/main.cpp index 79bbc63b0..e5ddb5652 100644 --- a/dash/examples/ex.01.hello-mpi/main.cpp +++ b/dash/examples/ex.01.hello-mpi/main.cpp @@ -1,3 +1,12 @@ +/** + * \example ex.01.hello-mpi/main.cpp + * A simple "hello world" example in which every unit sends a string to + * \c std::cout containing it's \c dash::myid() , the \c dash::size(), + * the name of the host, the version of the underlying runtime system, + * and it's process id. + */ + + #include #include #include diff --git a/dash/examples/ex.02.array-csr/main.cpp b/dash/examples/ex.02.array-csr/main.cpp index fe9d0c22e..91deafc0e 100644 --- a/dash/examples/ex.02.array-csr/main.cpp +++ b/dash/examples/ex.02.array-csr/main.cpp @@ -1,3 +1,10 @@ +/** + * \example ex.02.array-csr/main.cpp + * Example illustrating access to elements in a \c dash::Array by + * global index and the CSR pattern. + */ + + #include #include #include diff --git a/dash/examples/ex.02.array-delayed/main.cpp b/dash/examples/ex.02.array-delayed/main.cpp index 87497681a..766b101b7 100644 --- a/dash/examples/ex.02.array-delayed/main.cpp +++ b/dash/examples/ex.02.array-delayed/main.cpp @@ -1,3 +1,9 @@ +/** + * \example ex.02.array-delayed/main.cpp + * Example illustrating delayed allocation of a \c dash::Array + */ + + #include #include #include diff --git a/dash/examples/ex.03.globref/main.cpp b/dash/examples/ex.03.globref/main.cpp index 96c476ddd..9ceae0a7a 100644 --- a/dash/examples/ex.03.globref/main.cpp +++ b/dash/examples/ex.03.globref/main.cpp @@ -1,3 +1,9 @@ +/** + * \example ex.03.globref/main.cpp + * Example illustrating the use of DASH global + * references, i.e., \c dash::GlobRef + */ + #include #include #include diff --git a/dash/examples/ex.04.memalloc/main.cpp b/dash/examples/ex.04.memalloc/main.cpp index 6f21f3f31..986cefd59 100644 --- a/dash/examples/ex.04.memalloc/main.cpp +++ b/dash/examples/ex.04.memalloc/main.cpp @@ -1,3 +1,9 @@ +/** + * \example ex.04.memalloc/main.cpp + * Example demonstrating non-collective + * global memory allocation. + */ + #include #include #include diff --git a/dash/examples/ex.05.min_element/main.cpp b/dash/examples/ex.05.min_element/main.cpp index e39034607..976956ee0 100644 --- a/dash/examples/ex.05.min_element/main.cpp +++ b/dash/examples/ex.05.min_element/main.cpp @@ -1,3 +1,9 @@ +/** + * \example ex.05.min_element/main.cpp + * Example demonstrating different use-cases + * of \c dash::min_element. + */ + #include #include #include diff --git a/dash/examples/ex.06.pattern-block-visualizer/main.cpp b/dash/examples/ex.06.pattern-block-visualizer/main.cpp index cb16928aa..c91e3116e 100644 --- a/dash/examples/ex.06.pattern-block-visualizer/main.cpp +++ b/dash/examples/ex.06.pattern-block-visualizer/main.cpp @@ -1,3 +1,9 @@ +/** + * \example ex.06.pattern-block-visualizer/main.cpp + * Example demonstrating the instantiation of + * different patterns and their visualization. + */ + #include #include #include diff --git a/dash/examples/ex.06.pattern-visualizer/main.cpp b/dash/examples/ex.06.pattern-visualizer/main.cpp index c2a651a67..dc2c7433e 100644 --- a/dash/examples/ex.06.pattern-visualizer/main.cpp +++ b/dash/examples/ex.06.pattern-visualizer/main.cpp @@ -1,3 +1,10 @@ +/** + * \example ex.06.pattern-block-visualizer/main.cpp + * Example demonstrating the instantiation of + * different patterns and their visualization + * using \c dash::tools::PatternVisualizer. + */ + #include #include #include diff --git a/dash/examples/ex.06.std-algo/main.cpp b/dash/examples/ex.06.std-algo/main.cpp index 47bbe7b19..3998ccacd 100644 --- a/dash/examples/ex.06.std-algo/main.cpp +++ b/dash/examples/ex.06.std-algo/main.cpp @@ -1,3 +1,9 @@ +/** + * \example ex.06.std-algo/main.cpp + * Example demonstrating the use of STL + * algorithms on DASH global data structures. + */ + #include #include #include diff --git a/dash/examples/ex.08.io-hdf5-stream/main.cpp b/dash/examples/ex.08.io-hdf5-stream/main.cpp index 8019e900e..6a21d3964 100644 --- a/dash/examples/ex.08.io-hdf5-stream/main.cpp +++ b/dash/examples/ex.08.io-hdf5-stream/main.cpp @@ -1,3 +1,11 @@ +/** + * \example ex.08.io-hdf5/main.cpp + * Example demonstrating the use of + * \c dash::io::hdf5 to read and write + * HDF5 files using streams. + */ + + #include #include diff --git a/dash/examples/ex.08.io-hdf5/main.cpp b/dash/examples/ex.08.io-hdf5/main.cpp index f2902d05e..7929d5abb 100644 --- a/dash/examples/ex.08.io-hdf5/main.cpp +++ b/dash/examples/ex.08.io-hdf5/main.cpp @@ -1,3 +1,10 @@ +/** + * \example ex.08.io-hdf5/main.cpp + * Example demonstrating the use of + * \c dash::io::hdf5 to read and write + * HDF5 files. + */ + #include #include diff --git a/dash/examples/ex.10.radixsort/main.cpp b/dash/examples/ex.10.radixsort/main.cpp index 21d045568..277cd765d 100644 --- a/dash/examples/ex.10.radixsort/main.cpp +++ b/dash/examples/ex.10.radixsort/main.cpp @@ -1,3 +1,8 @@ +/** + * \example ex.10.radixsort/main.cpp + * Example demonstrating radixsort on + * DASH global data structures. + */ #include #include diff --git a/dash/examples/ex.11.simple-stencil/main.cpp b/dash/examples/ex.11.simple-stencil/main.cpp index 9c5a245f3..7fa831b9c 100644 --- a/dash/examples/ex.11.simple-stencil/main.cpp +++ b/dash/examples/ex.11.simple-stencil/main.cpp @@ -11,7 +11,7 @@ * This example implements a very simple blur filter. For simplicity * no real image is used, but an image containg circles is generated. * - * \TODO fix \cdash::copy problem + * \TODO fix \c dash::copy problem */ #include diff --git a/dash/include/dash/Matrix.h b/dash/include/dash/Matrix.h index 53075e47f..c31642093 100644 --- a/dash/include/dash/Matrix.h +++ b/dash/include/dash/Matrix.h @@ -24,7 +24,7 @@ * \defgroup DashMatrixConcept Matrix Concept * Concept for a distributed n-dimensional matrix. * - * Extends concepts \c DashContainerConcept and \c DashArrayConcept. + * Extends concepts \ref DashContainerConcept and \ref DashArrayConcept. * * \see DashContainerConcept * \see DashArrayConcept @@ -41,7 +41,7 @@ * * \par Types * - * As defined in \c DashContainerConcept. + * As defined in \ref DashContainerConcept. * * Type name | Description * ------------------------------- | ------------------------------------------------------------------------------------------------------------------- @@ -57,7 +57,7 @@ * const_reference | Reference on const container elements in global index space. * local_pointer | Native pointer on local container elements. * const_local_pointer | Native pointer on const local container elements. - * view_type | View specifier on container elements, model of \c DashViewConcept. + * view_type | View specifier on container elements, model of \ref DashViewConcept. * local_type | Reference to local element range, allows range-based iteration. * pattern_type | Concrete model of the Pattern concept that specifies the container's data distribution and cartesian access pattern. * @@ -69,7 +69,7 @@ * view_type | block | index_type bi | Matrix proxy object representing a view specifier on the matrix block at canonical block index bi. * view_type | block | index_type[d] bp | Matrix proxy object representing a view specifier on the matrix block at block coordinate bc. * - * As defined in \c DashContainerConcept: + * As defined in \ref DashContainerConcept: * * Return Type | Method | Parameters | Description * ------------------------ | --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- @@ -272,7 +272,7 @@ class Matrix * Default constructor, for delayed allocation. * * Sets the associated team to DART_TEAM_NULL for global matrix instances - * that are declared before \c dash::Init(). + * that are declared before \ref dash::Init(). */ Matrix( Team & team = dash::Team::Null()); @@ -487,7 +487,7 @@ class Matrix ) const; /** - * Subscript operator, returns a \cGlobRef if matrix has only one dimension + * Subscript operator, returns a \ref GlobRef if matrix has only one dimension */ template typename std::enable_if< @@ -509,7 +509,7 @@ class Matrix ); /** - * Subscript operator, returns a \cGlobRef if matrix has only one dimension + * Subscript operator, returns a \ref GlobRef if matrix has only one dimension */ template typename std::enable_if<(__NumViewDim == 0), reference>::type @@ -561,7 +561,7 @@ class Matrix * Projection to given offset in first sub-dimension (column), same as * \c sub<0>(n). * - * \returns A \c MatrixRef object representing the nth column + * \returns A \ref MatrixRef object representing the nth column * * \see sub * \see row @@ -574,7 +574,7 @@ class Matrix * Projection to given offset in first sub-dimension (column), same as * \c sub<0>(n). * - * \returns A \c MatrixRef object representing the nth column + * \returns A \ref MatrixRef object representing the nth column * * \see sub * \see row @@ -587,7 +587,7 @@ class Matrix * Projection to given offset in second sub-dimension (rows), same as * \c sub<1>(n). * - * \returns A \c MatrixRef object representing the nth row + * \returns A \ref MatrixRef object representing the nth row * * \see sub * \see col @@ -600,7 +600,7 @@ class Matrix * Projection to given offset in second sub-dimension (rows), same as * \c sub<1>(n). * - * \returns A \c MatrixRef object representing the nth row + * \returns A \ref MatrixRef object representing the nth row * * \see sub * \see col @@ -664,7 +664,7 @@ class Matrix ); /** - * Fortran-style subscript operator, alias for \c at(). + * Fortran-style subscript operator, alias for \ref at(). * As an example, the operation \c matrix(i,j) is equivalent to * \c matrix[i][j]. * @@ -714,7 +714,7 @@ class Matrix dash::HView hview(); /** - * Conversion operator to type \c MatrixRef. + * Conversion operator to type \ref MatrixRef. */ operator MatrixRef (); diff --git a/dash/include/dash/Mutex.h b/dash/include/dash/Mutex.h index 2eced05d3..97abceb99 100644 --- a/dash/include/dash/Mutex.h +++ b/dash/include/dash/Mutex.h @@ -11,10 +11,10 @@ namespace dash { /** - * Behaves similar to \cstd::mutex and is used to ensure mutual exclusion + * Behaves similar to \c std::mutex and is used to ensure mutual exclusion * within a dash team. * - * \note This works properly with \cstd::lock_guard + * \note This works properly with \c std::lock_guard * \note Mutex cannot be placed in DASH containers * * \code diff --git a/dash/include/dash/atomic/GlobAtomicRef.h b/dash/include/dash/atomic/GlobAtomicRef.h index 45f4e6f95..392c4aaa0 100644 --- a/dash/include/dash/atomic/GlobAtomicRef.h +++ b/dash/include/dash/atomic/GlobAtomicRef.h @@ -282,7 +282,7 @@ class GlobRef> } /** - * DASH specific variant which is faster than \cfetch_add + * DASH specific variant which is faster than \c fetch_add * but does not return value */ void add(const T & value) const @@ -304,7 +304,7 @@ class GlobRef> } /** - * DASH specific variant which is faster than \cfetch_sub + * DASH specific variant which is faster than \c fetch_sub * but does not return value */ void sub(const T & value) const diff --git a/dash/include/dash/matrix/MatrixRef.h b/dash/include/dash/matrix/MatrixRef.h index 5d8549291..5b5b135a8 100644 --- a/dash/include/dash/matrix/MatrixRef.h +++ b/dash/include/dash/matrix/MatrixRef.h @@ -41,8 +41,8 @@ template < class LocalMatrixRef; /** - * A view on a referenced \c Matrix object, such as a dimensional - * projection returned by \c Matrix::sub. + * A view on a referenced \ref Matrix object, such as a dimensional + * projection returned by \ref Matrix::sub. * * TODO: * Projection order matrix.sub().local() is not fully implemented yet. @@ -223,7 +223,7 @@ class MatrixRef constexpr operator[](index_type n) const; /** - * Subscript operator, returns a \cdash::GlobRef at given offset + * Subscript operator, returns a \ref dash::GlobRef at given offset * in global element range for last dimension. */ template @@ -231,7 +231,7 @@ class MatrixRef operator[](index_type n); /** - * Subscript operator, returns a \cdash::GlobRef at given offset + * Subscript operator, returns a \ref dash::GlobRef at given offset * in global element range for last dimension. */ template @@ -347,7 +347,7 @@ class MatrixRef const ::std::array & coords); /** - * Fortran-style subscript operator, alias for \c at(). + * Fortran-style subscript operator, alias for \ref at(). * As an example, the operation \c matrix(i,j) is equivalent to * \c matrix[i][j]. * From f26d11880c81c4f4e38a9c2c6fd6a05298682df1 Mon Sep 17 00:00:00 2001 From: Joseph Schuchart Date: Thu, 30 Mar 2017 10:17:05 +0200 Subject: [PATCH 2/5] Fix documentation of dash::find_if and friends and fix return value of dash::any_of and dash::all_of --- dash/include/dash/algorithm/AllOf.h | 14 +++++++++++--- dash/include/dash/algorithm/AnyOf.h | 11 +++++++++-- dash/include/dash/algorithm/Find.h | 18 ++++++++++++++++-- 3 files changed, 36 insertions(+), 7 deletions(-) diff --git a/dash/include/dash/algorithm/AllOf.h b/dash/include/dash/algorithm/AllOf.h index 86f2b6239..8644f90b6 100644 --- a/dash/include/dash/algorithm/AllOf.h +++ b/dash/include/dash/algorithm/AllOf.h @@ -7,14 +7,22 @@ namespace dash { + /** - * \ingroup DashAlgorithms + * Check whether all element in the range satisfy predicate \c p. + * + * \returns \c true if all elements satisfy \c p, \c false otherwise. + * + * \see dash::find_if + * \see dash::find_if_not + * \see dash::any_of + * \ingroup DashAlgorithms */ template< typename ElementType, class PatternType, - typename UnaryPredicate> -GlobIter all_of( + typename UnaryPredicate> +bool all_of( /// Iterator to the initial position in the sequence GlobIter first, /// Iterator to the final position in the sequence diff --git a/dash/include/dash/algorithm/AnyOf.h b/dash/include/dash/algorithm/AnyOf.h index 3597716d2..e8c9a7257 100644 --- a/dash/include/dash/algorithm/AnyOf.h +++ b/dash/include/dash/algorithm/AnyOf.h @@ -8,13 +8,20 @@ namespace dash { /** - * \ingroup DashAlgorithms + * Check whether any element in the range satisfies predicate \c p. + * + * \returns \c true if at least one element satisfies \c p, \c false otherwise. + * + * \see dash::find_if + * \see dash::find_if_not + * \see dash::all_of + * \ingroup DashAlgorithms */ template< typename ElementType, class PatternType, typename UnaryPredicate > -GlobIter any_of( +bool any_of( /// Iterator to the initial position in the sequence GlobIter first, /// Iterator to the final position in the sequence diff --git a/dash/include/dash/algorithm/Find.h b/dash/include/dash/algorithm/Find.h index 92a8eac5c..243fd0aef 100644 --- a/dash/include/dash/algorithm/Find.h +++ b/dash/include/dash/algorithm/Find.h @@ -86,19 +86,26 @@ GlobIter find( } /** + * Returns an iterator to the first element in the range \c [first,last) that + * satisfies the predicate \c p. + * If no such element is found, the function returns \c last. + * + * \see dash::find + * \see dash::find_if_not + * * \ingroup DashAlgorithms */ template< typename ElementType, class PatternType, - class UnaryPredicate > + class UnaryPredicate > GlobIter find_if( /// Iterator to the initial position in the sequence GlobIter first, /// Iterator to the final position in the sequence GlobIter last, /// Predicate which will be applied to the elements in range [first, last) - UnaryPredicate predicate) + UnaryPredicate predicate) { typedef typename PatternType::index_type index_t; @@ -140,6 +147,13 @@ GlobIter find_if( } /** + * Returns an iterator to the first element in the range \c [first,last) that + * does not satisfy the predicate \c p. + * If no such element is found, the function returns \c last. + * + * \see dash::find + * \see dash::find_if_not + * * \ingroup DashAlgorithms */ template< From 7e53ac0d3bf50bb87e6d97ed2142627eb8cd74af Mon Sep 17 00:00:00 2001 From: Joseph Schuchart Date: Thu, 30 Mar 2017 10:18:07 +0200 Subject: [PATCH 3/5] Fix documentation across DART and DASH --- .../include/dash/dart/if/dart_communication.h | 2 - dart-if/include/dash/dart/if/dart_globmem.h | 10 ++-- dart-if/include/dash/dart/if/dart_handle.h | 46 +++++++++++++++++++ .../dash/dart/if/dart_initialization.h | 5 +- .../dash/dart/if/dart_synchronization.h | 1 - dart-if/include/dash/dart/if/dart_types.h | 22 +++++++-- dash/include/dash/Array.h | 46 ++++++++++++------- dash/include/dash/Container.h | 26 +++++------ dash/include/dash/List.h | 5 +- dash/include/dash/Matrix.h | 28 +++++------ dash/include/dash/Mutex.h | 2 +- dash/include/dash/io/hdf5/InputStream.h | 6 +-- dash/include/dash/io/hdf5/OutputStream.h | 6 +-- dash/include/dash/io/hdf5/StorageDriver.h | 6 +-- 14 files changed, 141 insertions(+), 70 deletions(-) create mode 100644 dart-if/include/dash/dart/if/dart_handle.h diff --git a/dart-if/include/dash/dart/if/dart_communication.h b/dart-if/include/dash/dart/if/dart_communication.h index 3f5a3b830..26004704b 100644 --- a/dart-if/include/dash/dart/if/dart_communication.h +++ b/dart-if/include/dash/dart/if/dart_communication.h @@ -236,7 +236,6 @@ dart_ret_t dart_reduce( * \param nelem The number of local elements to accumulate per unit. * \param dtype The data type to use in the accumulate operation \c op. * \param op The accumulation operation to perform. - * \param team The team to participate in the accumulate. * * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * @@ -266,7 +265,6 @@ dart_ret_t dart_accumulate( * \c op. * \param dtype The data type to use in the operation \c op. * \param op The operation to perform. - * \param team The team to participate in the operation. * * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * diff --git a/dart-if/include/dash/dart/if/dart_globmem.h b/dart-if/include/dash/dart/if/dart_globmem.h index 6a0657129..5969b042d 100644 --- a/dart-if/include/dash/dart/if/dart_globmem.h +++ b/dart-if/include/dash/dart/if/dart_globmem.h @@ -219,8 +219,8 @@ dart_ret_t dart_gptr_setunit( /** * Get the flags field for the segment specified by the global pointer. * - * \param gptr Global Pointer describing a segment. - * \param unit The flags to get for segment in \c gptr + * \param gptr Global Pointer describing a segment. + * \param flags The flags to get for segment in \c gptr * * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * @@ -239,8 +239,8 @@ dart_ret_t dart_gptr_getflags( * fast access. The remaining flags can be queried through * \ref dart_gptr_getflags. * - * \param gptr Global Pointer describing a segment. - * \param unit The flags to set for segment in \c gptr + * \param gptr Global Pointer describing a segment. + * \param flags The flags to set for segment in \c gptr * * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * @@ -330,7 +330,6 @@ dart_ret_t dart_team_memalloc_aligned( * After this operation, the global pointer can be reset using * \ref DART_GPTR_NULL. * - * \param teamid The team to participate in the collective deallocation. * \param gptr Global pointer pointing to the memory to deallocate. * * \see DART_GPTR_NULL @@ -397,7 +396,6 @@ dart_ret_t dart_team_memregister( * externally allocated memory. * Does not de-allocate memory. * - * \param teamid The team to participate in the collective operation. * \param gptr Pointer to a global pointer object to set up. * * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. diff --git a/dart-if/include/dash/dart/if/dart_handle.h b/dart-if/include/dash/dart/if/dart_handle.h new file mode 100644 index 000000000..5106a7474 --- /dev/null +++ b/dart-if/include/dash/dart/if/dart_handle.h @@ -0,0 +1,46 @@ +#ifndef DART_HANDLE_H_ +#define DART_HANDLE_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +/** \cond DART_HIDDEN_SYMBOLS */ +#define DART_INTERFACE_ON +/** \endcond */ + +/* + * \file dart_handle.h + * + * Functions for handling of asynchronous handles. + */ + +#include + +/** + * Handle returned by asynchronous operations to wait for a specific + * operation to complete using \c dart_wait etc. + */ +typedef struct dart_handle_struct * dart_handle_t; + +dart_ret_t +dart_test( + dart_handle_t handle, + int32_t * result); + +dart_ret_t +dart_wait( + dart_handle_t handle, + int32_t * result); + + +/** \cond DART_HIDDEN_SYMBOLS */ +#define DART_INTERFACE_OFF +/** \endcond */ + +#ifdef __cplusplus +} +#endif + + +#endif /* DART_HANDLE_H_ */ diff --git a/dart-if/include/dash/dart/if/dart_initialization.h b/dart-if/include/dash/dart/if/dart_initialization.h index 347445cc2..dcc875efc 100644 --- a/dart-if/include/dash/dart/if/dart_initialization.h +++ b/dart-if/include/dash/dart/if/dart_initialization.h @@ -44,7 +44,7 @@ dart_ret_t dart_init(int *argc, char ***argv) DART_NOTHROW; * \param argc Pointer to the number of command line arguments. * \param argv Pointer to the array of command line arguments. * \param[out] thread_safety The provided thread safety, - * one of \ref dart_thread_level_t. + * one of \ref dart_thread_support_level_t. * * \return \c DART_OK on sucess or an error code from \see dart_ret_t otherwise. * @@ -83,6 +83,9 @@ bool dart_initialized() DART_NOTHROW; * * \c dart_abort tries to call the underlying runtime's abort function * (such as \c MPI_Abort) and is guaranteed to not return. + * + * \threadsafe_none + * \ingroup DartInitialization */ void dart_abort(int errorcode) __attribute__((noreturn)); diff --git a/dart-if/include/dash/dart/if/dart_synchronization.h b/dart-if/include/dash/dart/if/dart_synchronization.h index 6c7a214ef..968acad2a 100644 --- a/dart-if/include/dash/dart/if/dart_synchronization.h +++ b/dart-if/include/dash/dart/if/dart_synchronization.h @@ -49,7 +49,6 @@ dart_ret_t dart_team_lock_init( * Collective operation to destroy a \c lock initialized using * \ref dart_team_lock_init. * - * \param teamid The team this lock is used on. * \param lock The \c lock to free. * \return \c DART_OK on sucess or an error code from \ref dart_ret_t otherwise. * diff --git a/dart-if/include/dash/dart/if/dart_types.h b/dart-if/include/dash/dart/if/dart_types.h index 3da45b077..d69fb8409 100644 --- a/dart-if/include/dash/dart/if/dart_types.h +++ b/dart-if/include/dash/dart/if/dart_types.h @@ -99,7 +99,7 @@ typedef enum typedef enum { DART_TYPE_UNDEFINED = 0, - /** integral data types */ + /// integral data types DART_TYPE_BYTE, DART_TYPE_SHORT, DART_TYPE_INT, @@ -107,14 +107,14 @@ typedef enum DART_TYPE_LONG, DART_TYPE_ULONG, DART_TYPE_LONGLONG, - /** floating point data types */ + /// floating point data types DART_TYPE_FLOAT, DART_TYPE_DOUBLE, - /** Reserved, do not use! */ + /// Reserved, do not use! DART_TYPE_COUNT } dart_datatype_t; - +/** size for integral \c size_t */ #if (UINT32_MAX == SIZE_MAX) # define DART_TYPE_SIZET DART_TYPE_UINT #elif (UINT64_MAX == SIZE_MAX) @@ -124,10 +124,16 @@ typedef enum #endif +/** \cond DART_HIDDEN_SYMBOLS */ +/** + * \todo This is not part of the DART interface + * and should move to dash::internal eventually. + */ typedef struct { dart_datatype_t dtype; int nelem; } dart_storage_t; +/** \endcond */ /** * Data type for storing a unit ID @@ -240,6 +246,14 @@ typedef int16_t dart_team_t; #define DART_UNDEFINED_TEAM_ID ((dart_team_t)(-1)) +/** + * Levels of thread-support offered by DART. + * \ref DART_THREAD_MULTIPLE is supported if + * DART has been build with \c DART_ENABLE_THREADSUPPORT + * and the underlying communication backend supports + * thread-safe access. + * + */ typedef enum { /** No support for thread-based concurrency in DART is provided. */ diff --git a/dash/include/dash/Array.h b/dash/include/dash/Array.h index 5c972d0c3..d78a6c463 100644 --- a/dash/include/dash/Array.h +++ b/dash/include/dash/Array.h @@ -32,10 +32,10 @@ * A distributed array of fixed size. * * Like all DASH containers, \c dash::Array is initialized by specifying - * an arrangement of units in a team (\c dash::TeamSpec) and a - * distribution pattern (\c dash::Pattern). + * an arrangement of units in a team (\ref dash::TeamSpec) and a + * distribution pattern (\ref dash::Pattern). * - * DASH arrays support delayed allocation (\c dash::Array::allocate), + * DASH arrays support delayed allocation (\ref dash::Array::allocate), * so global memory of an array instance can be allocated any time after * declaring a \c dash::Array variable. * @@ -61,19 +61,19 @@ * * \par Methods * - * Return Type | Method | Parameters | Description - * ------------------------ | --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- - * local_type | local |   | Container proxy object representing a view specifier on the container's local elements. - * pattern_type | pattern |   | Object implementing the Pattern concept specifying the container's data distribution and iteration pattern. - * iterator | begin |   | Iterator referencing the first container element. - * iterator | end |   | Iterator referencing the element past the last container element. - * Element * | lbegin |   | Native pointer referencing the first local container element, same as local().begin(). - * Element * | lend |   | Native pointer referencing the element past the last local container element, same as local().end(). - * size_type | size |   | Number of elements in the container. - * size_type | local_size |   | Number of local elements in the container, same as local().size(). - * bool | is_local | index_type gi | Whether the element at the given linear offset in global index space gi is local. - * bool | allocate | size_type n, DistributionSpec
ds, Team t | Allocation of n container elements distributed in Team t as specified by distribution spec ds - * void | deallocate |   | Deallocation of the container and its elements. + * Return Type | Method | Parameters | Description + * ------------------------ | --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- + * local_type | local |   | Container proxy object representing a view specifier on the container's local elements. + * pattern_type | pattern |   | Object implementing the Pattern concept specifying the container's data distribution and iteration pattern. + * iterator | begin |   | Iterator referencing the first container element. + * iterator | end |   | Iterator referencing the element past the last container element. + * Element * | lbegin |   | Native pointer referencing the first local container element, same as local().begin(). + * Element * | lend |   | Native pointer referencing the element past the last local container element, same as local().end(). + * size_type | size |   | Number of elements in the container. + * size_type | local_size |   | Number of local elements in the container, same as local().size(). + * bool | is_local | index_type gi | Whether the element at the given linear offset in global index space gi is local. + * bool | allocate | size_type n, DistributionSpec\ ds, Team t | Allocation of n container elements distributed in Team t as specified by distribution spec ds + * void | deallocate |   | Deallocation of the container and its elements. * * \} * @@ -1209,6 +1209,10 @@ class Array return m_pattern; } + /** + * Delayed allocation of global memory using a + * one-dimensional distribution spec. + */ bool allocate( size_type nelem, dash::DistributionSpec<1> distribution, @@ -1239,6 +1243,11 @@ class Array return ret; } + /** + * Delayed allocation of global memory using a + * one-dimensional distribution spec and + * initializing values. + */ bool allocate( size_type nelem, std::initializer_list local_elements, @@ -1295,9 +1304,12 @@ class Array DASH_LOG_TRACE_VAR("Array.deallocate >", this); } + /** + * Delayed allocation of global memory using the specified pattern. + */ bool allocate(const PatternType & pattern) { - DASH_LOG_TRACE("Array._allocate()", "pattern", + DASH_LOG_TRACE("Array._allocate()", "pattern", pattern.memory_layout().extents()); if (&m_pattern != &pattern) { DASH_LOG_TRACE("Array.allocate()", "using specified pattern"); diff --git a/dash/include/dash/Container.h b/dash/include/dash/Container.h index 255fcdc97..fdda6fb29 100644 --- a/dash/include/dash/Container.h +++ b/dash/include/dash/Container.h @@ -43,19 +43,19 @@ * * \par Member Functions * - * Return Type | Method | Parameters | Description - * ------------------------ | --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- - * local_type | local |   | Container proxy object representing a view specifier on the container's local elements. - * pattern_type | pattern |   | Object implementing the Pattern concept specifying the container's data distribution and iteration pattern. - * iterator | begin |   | Iterator referencing the first container element. - * iterator | end |   | Iterator referencing the element past the last container element. - * Element * | lbegin |   | Native pointer referencing the first local container element, same as local().begin(). - * Element * | lend |   | Native pointer referencing the element past the last local container element, same as local().end(). - * size_type | size |   | Number of elements in the container. - * size_type | local_size |   | Number of local elements in the container, same as local().size(). - * bool | is_local | index_type gi | Whether the element at the given linear offset in global index space gi is local. - * bool | allocate | size_type n, DistributionSpec
ds, Team t | Allocation of n container elements distributed in Team t as specified by distribution spec ds - * void | deallocate |   | Deallocation of the container and its elements. + * Return Type | Method | Parameters | Description + * ------------------------ | --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- + * local_type | local |   | Container proxy object representing a view specifier on the container's local elements. + * pattern_type | pattern |   | Object implementing the Pattern concept specifying the container's data distribution and iteration pattern. + * iterator | begin |   | Iterator referencing the first container element. + * iterator | end |   | Iterator referencing the element past the last container element. + * Element * | lbegin |   | Native pointer referencing the first local container element, same as local().begin(). + * Element * | lend |   | Native pointer referencing the element past the last local container element, same as local().end(). + * size_type | size |   | Number of elements in the container. + * size_type | local_size |   | Number of local elements in the container, same as local().size(). + * bool | is_local | index_type gi | Whether the element at the given linear offset in global index space gi is local. + * bool | allocate | size_type n, DistributionSpec\ ds, Team t | Allocation of n container elements distributed in Team t as specified by distribution spec ds + * void | deallocate |   | Deallocation of the container and its elements. * * \par Non-member Functions * diff --git a/dash/include/dash/List.h b/dash/include/dash/List.h index 7c0b90bd6..65d0596d7 100644 --- a/dash/include/dash/List.h +++ b/dash/include/dash/List.h @@ -96,7 +96,8 @@ namespace dash { * * Usage examples: * - * \code + * + * * size_t initial_local_capacity = 100; * size_t initial_capacity = dash::size() * initial_local_capacity; * dash::List list(initial_capacity); @@ -156,7 +157,7 @@ namespace dash { * // .-- 3 <-' | .-- 8 <-' | .-- 13 --' * // `-> 4 ----' `-> 9 ----' `-> 14 ---> Nil * - * \endcode + * */ /** diff --git a/dash/include/dash/Matrix.h b/dash/include/dash/Matrix.h index c31642093..5a8aa1342 100644 --- a/dash/include/dash/Matrix.h +++ b/dash/include/dash/Matrix.h @@ -69,21 +69,21 @@ * view_type | block | index_type bi | Matrix proxy object representing a view specifier on the matrix block at canonical block index bi. * view_type | block | index_type[d] bp | Matrix proxy object representing a view specifier on the matrix block at block coordinate bc. * - * As defined in \ref DashContainerConcept: + * As defined in \ref DashContainerConcept : * - * Return Type | Method | Parameters | Description - * ------------------------ | --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- - * local_type | local |   | Container proxy object representing a view specifier on the container's local elements. - * pattern_type | pattern |   | Object implementing the Pattern concept specifying the container's data distribution and iteration pattern. - * iterator | begin |   | Iterator referencing the first container element. - * iterator | end |   | Iterator referencing the element past the last container element. - * Element * | lbegin |   | Native pointer referencing the first local container element, same as local().begin(). - * Element * | lend |   | Native pointer referencing the element past the last local container element, same as local().end(). - * size_type | size |   | Number of elements in the container. - * size_type | local_size |   | Number of local elements in the container, same as local().size(). - * bool | is_local | index_type gi | Whether the element at the given linear offset in global index space gi is local. - * bool | allocate | size_type n, DistributionSpec
ds, Team t | Allocation of n container elements distributed in Team t as specified by distribution spec ds - * void | deallocate |   | Deallocation of the container and its elements. + * Return Type | Method | Parameters | Description + * ------------------------ | --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- + * local_type | local |   | Container proxy object representing a view specifier on the container's local elements. + * pattern_type | pattern |   | Object implementing the Pattern concept specifying the container's data distribution and iteration pattern. + * iterator | begin |   | Iterator referencing the first container element. + * iterator | end |   | Iterator referencing the element past the last container element. + * Element * | lbegin |   | Native pointer referencing the first local container element, same as local().begin(). + * Element * | lend |   | Native pointer referencing the element past the last local container element, same as local().end(). + * size_type | size |   | Number of elements in the container. + * size_type | local_size |   | Number of local elements in the container, same as local().size(). + * bool | is_local | index_type gi | Whether the element at the given linear offset in global index space gi is local. + * bool | allocate | size_type n, DistributionSpec\ ds, Team t | Allocation of n container elements distributed in Team t as specified by distribution spec ds + * void | deallocate |   | Deallocation of the container and its elements. * * \} */ diff --git a/dash/include/dash/Mutex.h b/dash/include/dash/Mutex.h index 97abceb99..9ed5d7737 100644 --- a/dash/include/dash/Mutex.h +++ b/dash/include/dash/Mutex.h @@ -69,7 +69,7 @@ class Mutex { bool try_lock(); /** - * Release the lock acquired through \clock() or \ctry_lock(). + * Release the lock acquired through \c lock() or \c try_lock(). */ void unlock(); diff --git a/dash/include/dash/io/hdf5/InputStream.h b/dash/include/dash/io/hdf5/InputStream.h index 21a93d8f6..8b5d841f8 100644 --- a/dash/include/dash/io/hdf5/InputStream.h +++ b/dash/include/dash/io/hdf5/InputStream.h @@ -37,10 +37,10 @@ class InputStream : public ::dash::io::IOSBase { /** * Creates an HDF5 input stream using a launch policy * - * Support of \cdash::launch::async is still highly experimental and requires + * Support of \ref dash::launch::async is still highly experimental and requires * thread support in MPI. If multi-threaded access is not supported, * blocking I/O is used as fallback. To wait for outstanding IO operations - * use \cflush(). Until the stream is not flushed, no write accesses to the + * use \c flush(). Until the stream is not flushed, no write accesses to the * container, as well as no barriers are allowed. * Otherwise the behavior is undefined. */ @@ -84,7 +84,7 @@ class InputStream : public ::dash::io::IOSBase { /** * Synchronizes with the data source. - * If \cdash::launch::async is used, waits until all data is read + * If \ref dash::launch::async is used, waits until all data is read */ InputStream flush() { DASH_LOG_DEBUG("flush input stream", _async_ops.size()); diff --git a/dash/include/dash/io/hdf5/OutputStream.h b/dash/include/dash/io/hdf5/OutputStream.h index 7963e4f0a..711aa386f 100644 --- a/dash/include/dash/io/hdf5/OutputStream.h +++ b/dash/include/dash/io/hdf5/OutputStream.h @@ -45,10 +45,10 @@ class OutputStream : public ::dash::io::IOSBase { /** * Creates an HDF5 output stream using a launch policy * - * Support of \cdash::launch::async is still highly experimental and requires + * Support of \ref dash::launch::async is still highly experimental and requires * thread support in MPI. If multi-threaded access is not supported, * blocking I/O is used as fallback. To wait for outstanding IO operations use - * \cflush(). Until the stream is not flushed, no write accesses to the + * \c flush(). Until the stream is not flushed, no write accesses to the * container, as well as no barriers are allowed. * Otherwise the behavior is undefined. */ @@ -99,7 +99,7 @@ class OutputStream : public ::dash::io::IOSBase { /** * Synchronizes with the data sink. - * If \cdash::launch::async is used, waits until all data is written + * If \ref dash::launch::async is used, waits until all data is written */ OutputStream flush() { DASH_LOG_DEBUG("flush output stream", _async_ops.size()); diff --git a/dash/include/dash/io/hdf5/StorageDriver.h b/dash/include/dash/io/hdf5/StorageDriver.h index f8fb859aa..47c2ffbc7 100644 --- a/dash/include/dash/io/hdf5/StorageDriver.h +++ b/dash/include/dash/io/hdf5/StorageDriver.h @@ -127,7 +127,7 @@ class StoreHDF { std::string datapath, /// options how to open and modify data hdf5_options foptions = hdf5_options(), - /// \cstd::function to convert native type into h5 type + /// \c std::function to convert native type into h5 type type_converter_fun_type to_h5_dt_converter = get_h5_datatype< typename dash::view_traits::origin_type::value_type>) { using Container_t = typename dash::view_traits::origin_type; @@ -274,7 +274,7 @@ class StoreHDF { std::string datapath, /// options how to open and modify data hdf5_options foptions = hdf5_options(), - /// \cstd::function to convert native type into h5 type + /// \c std::function to convert native type into h5 type type_converter_fun_type to_h5_dt_converter = get_h5_datatype) { using pattern_t = typename Container_t::pattern_type; @@ -398,7 +398,7 @@ class StoreHDF { std::string datapath, /// options how to open and modify data hdf5_options foptions = hdf5_options(), - /// \cstd::function to convert native type into h5 type + /// \c std::function to convert native type into h5 type type_converter_fun_type to_h5_dt_converter = get_h5_datatype) {} From a0572ac4791914c60aab61b1d69248d8e8bf6021 Mon Sep 17 00:00:00 2001 From: Joseph Schuchart Date: Thu, 30 Mar 2017 10:18:38 +0200 Subject: [PATCH 4/5] use \todo instead of \TODO --- dash/examples/ex.11.simple-stencil/main.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dash/examples/ex.11.simple-stencil/main.cpp b/dash/examples/ex.11.simple-stencil/main.cpp index 7fa831b9c..aba6ed164 100644 --- a/dash/examples/ex.11.simple-stencil/main.cpp +++ b/dash/examples/ex.11.simple-stencil/main.cpp @@ -11,7 +11,7 @@ * This example implements a very simple blur filter. For simplicity * no real image is used, but an image containg circles is generated. * - * \TODO fix \c dash::copy problem + * \todo fix \c dash::copy problem */ #include From 176b22b9108add90163ad4f9e1db18a2a1725e1b Mon Sep 17 00:00:00 2001 From: Joseph Schuchart Date: Thu, 30 Mar 2017 11:07:01 +0200 Subject: [PATCH 5/5] Remove dart_handle.h that should not have been here --- dart-if/include/dash/dart/if/dart_handle.h | 46 ---------------------- 1 file changed, 46 deletions(-) delete mode 100644 dart-if/include/dash/dart/if/dart_handle.h diff --git a/dart-if/include/dash/dart/if/dart_handle.h b/dart-if/include/dash/dart/if/dart_handle.h deleted file mode 100644 index 5106a7474..000000000 --- a/dart-if/include/dash/dart/if/dart_handle.h +++ /dev/null @@ -1,46 +0,0 @@ -#ifndef DART_HANDLE_H_ -#define DART_HANDLE_H_ - -#ifdef __cplusplus -extern "C" { -#endif - -/** \cond DART_HIDDEN_SYMBOLS */ -#define DART_INTERFACE_ON -/** \endcond */ - -/* - * \file dart_handle.h - * - * Functions for handling of asynchronous handles. - */ - -#include - -/** - * Handle returned by asynchronous operations to wait for a specific - * operation to complete using \c dart_wait etc. - */ -typedef struct dart_handle_struct * dart_handle_t; - -dart_ret_t -dart_test( - dart_handle_t handle, - int32_t * result); - -dart_ret_t -dart_wait( - dart_handle_t handle, - int32_t * result); - - -/** \cond DART_HIDDEN_SYMBOLS */ -#define DART_INTERFACE_OFF -/** \endcond */ - -#ifdef __cplusplus -} -#endif - - -#endif /* DART_HANDLE_H_ */