diff --git a/dart-if/v3.2/include/dash/dart/if/dart.h b/dart-if/v3.2/include/dash/dart/if/dart.h index 37c0ed0dc..79df7bec2 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart.h +++ b/dart-if/v3.2/include/dash/dart/if/dart.h @@ -87,8 +87,10 @@ extern "C" { /* --- DART version and build date --- */ +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_VERSION_STR "3.2.0" #define DART_BUILD_STR (__DATE__ " " __TIME__) +/** \endcond */ /* --- DART types and return values diff --git a/dart-if/v3.2/include/dash/dart/if/dart_communication.h b/dart-if/v3.2/include/dash/dart/if/dart_communication.h index 3cd0a92c3..16ca29404 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart_communication.h +++ b/dart-if/v3.2/include/dash/dart/if/dart_communication.h @@ -7,14 +7,15 @@ /** * \file dart_communication.h * - * A set of basic collective communication routines in DART. + * \brief A set of basic communication routines in DART. + * * The semantics of the routines below are the same as with MPI. The only - * difference is that DART doesn't specify data types and the operates on - * raw buffers instead. Message size is thus specified in bytes. + * difference is that DART doesn't specify data types but operates on + * raw buffers instead. Message sizes are thus specified in bytes. */ /** - * \defgroup DartCommunication Collective communication routines in DART + * \defgroup DartCommunication Communication routines in DART * \ingroup DartInterface * */ @@ -22,15 +23,40 @@ extern "C" { #endif +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_ON +/** \endcond */ + +/** + * \name Collective operations + * Collective operations involving all units of a given team. + */ + +/** \{ */ +/** + * DART Equivalent to MPI_Barrier + * + * \param team The team to perform a barrier on. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication + */ dart_ret_t dart_barrier( dart_team_t team); /** * DART Equivalent to MPI broadcast. * - * \ingroup DartCommuncation + * \param buf Buffer that is the source (on \c root) or the destination of the broadcast. + * \param nbytes The number of bytes to broadcast/receive. + * \param root The unit that broadcasts data to all other members in \c team + * \param team The team to participate in the broadcast. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_bcast( void *buf, @@ -41,7 +67,15 @@ dart_ret_t dart_bcast( /** * DART Equivalent to MPI scatter. * - * \ingroup DartCommuncation + * \param sendbuf The buffer containing the data to be sent by unit \c root. + * \param recvbuf The buffer to hold the received data. + * \param nbytes Number of bytes sent to each process and received by each unit. + * \param root The unit that scatters data to all units in \c team. + * \param team The team to participate in the scatter. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_scatter( void *sendbuf, @@ -53,7 +87,15 @@ dart_ret_t dart_scatter( /** * DART Equivalent to MPI gather. * - * \ingroup DartCommuncation + * \param sendbuf The buffer containing the data to be sent by each unit. + * \param recvbuf The buffer to hold the received data on unit \c root. + * \param nbytes Number of bytes sent by each process and received from each unit at unit \c root. + * \param root The unit that gathers all data from units in \c team. + * \param team The team to participate in the gather. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_gather( void *sendbuf, @@ -65,7 +107,14 @@ dart_ret_t dart_gather( /** * DART Equivalent to MPI allgather. * - * \ingroup DartCommuncation + * \param sendbuf The buffer containing the data to be sent by each unit. + * \param recvbuf The buffer to hold the received data. + * \param nbytes Number of bytes sent by each process and received from each unit. + * \param team The team to participate in the allgather. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_allgather( void *sendbuf, @@ -76,25 +125,43 @@ dart_ret_t dart_allgather( /** * DART Equivalent to MPI allgatherv. * - * \ingroup DartCommuncation + * \param sendbuf The buffer containing the data to be sent by each unit. + * \param nsendbytes Number of bytes to be sent by this unit. + * \param recvbuf The buffer to hold the received data. + * \param nrecvbytes Array containing the number of bytes to receive from each unit. + * \param recvdispls Array containing the displacements of data received from each unit in \c recvbuf. + * \param teamid The team to participate in the allgatherv. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_allgatherv( void * sendbuf, size_t nsendbytes, void * recvbuf, - int * nrecvcounts, + int * nrecvbytes, int * recvdispls, dart_team_t teamid); /** * DART Equivalent to MPI allreduce. * - * \ingroup DartCommuncation + * \param sendbuf The buffer containing the data to be sent by each unit. + * \param recvbuf The buffer to hold the received data. + * \param nelem Number of elements sent by each process and received from each unit. + * \param dtype The data type to use in the reduction operation \c op. + * \param op The reduction operation to perform. + * \param team The team to participate in the allreduce. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_allreduce( void * sendbuf, void * recvbuf, - size_t nbytes, + size_t nelem, dart_datatype_t dtype, dart_operation_t op, dart_team_t team); @@ -102,44 +169,29 @@ dart_ret_t dart_allreduce( /** * DART Equivalent to MPI reduce. * - * \ingroup DartCommuncation + * \todo Why is this not generic? + * + * \ingroup DartCommunication */ dart_ret_t dart_reduce_double( double *sendbuf, double *recvbuf, dart_team_t team); -typedef struct dart_handle_struct * dart_handle_t; /** - * 'REGULAR' variant of dart_get. - * When this functions returns, neither local nor remote completion - * is guaranteed. A later fence/flush operation is needed to guarantee - * local and remote completion. + * DART Equivalent to MPI_Accumulate. * - * \ingroup DartCommuncation - */ -dart_ret_t dart_get( - void * dest, - dart_gptr_t ptr, - size_t nbytes); -/** - * 'REGULAR' variant of dart_put. - * When this functions returns, neither local nor remote completion - * is guaranteed. A later fence/flush operation is needed to guarantee - * local and remote completion. + * \param gptr A global pointer determining the target of the accumulate operation. + * \param values The local buffer holding the elements to accumulate. + * \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. * - * \ingroup DartCommuncation - */ -dart_ret_t dart_put( - dart_gptr_t ptr, - const void * src, - size_t nbytes); - -/** - * DART Equivalent to MPI_Accumulate. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * - * \ingroup DartCommuncation + * \ingroup DartCommunication */ dart_ret_t dart_accumulate( dart_gptr_t gptr, @@ -152,7 +204,16 @@ dart_ret_t dart_accumulate( /** * DART Equivalent to MPI_Fetch_and_op. * - * \ingroup DartCommuncation + * \param gptr A global pointer determining the target of the fetch-and-op operation. + * \param value Pointer to an element of type \c dtype to be involved in operation \c op on the value referenced by \c gptr. + * \param result Pointer to an element of type \c dtype to hold the value of the element referenced by \c gptr before the operation \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. + * + * \ingroup DartCommunication */ dart_ret_t dart_fetch_and_op( dart_gptr_t gptr, @@ -162,151 +223,310 @@ dart_ret_t dart_fetch_and_op( dart_operation_t op, dart_team_t team); + +/** \} */ + + /** - * 'HANDLE' variant of dart_get. - * Neither local nor remote completion is guaranteed. A later - * dart_wait*() call or a fence/flush operation is needed to guarantee - * completion. - * - * \ingroup DartCommuncation + * \name Non-blocking single-sided communication routines + * DART single-sided communication routines that return without guaranteeing completion. + * Completion will be guaranteed after a flush operation. */ -dart_ret_t dart_get_handle( - void * dest, - dart_gptr_t ptr, - size_t nbytes, - /// [OUT] Pointer to DART handle to instantiate for later use with - /// \c dart_wait, \c dart_wait_all etc. - dart_handle_t * handle); +/** \{ */ /** - * 'HANDLE' variant of dart_put. - * Neither local nor remote completion is guaranteed. A later - * dart_wait*() call or a fence/flush operation is needed to guarantee - * completion. + * 'REGULAR' variant of dart_get. + * Copy data referenced by a global pointer into local memory. + * When this functions returns, neither local nor remote completion + * is guaranteed. A later flush operation is needed to guarantee + * local and remote completion. * - * \ingroup DartCommuncation + * \param dest The local destination buffer to store the data to. + * \param gptr A global pointer determining the source of the get operation. + * \param nbytes The number of bytes to transfer. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ -dart_ret_t dart_put_handle( - dart_gptr_t ptr, - const void * src, - size_t nbytes, - /// [OUT] Pointer to DART handle to instantiate for later use with - /// \c dart_wait, \c dart_wait_all etc. - dart_handle_t * handle); +dart_ret_t dart_get( + void * dest, + dart_gptr_t gptr, + size_t nbytes); /** - * 'BLOCKING' variant of dart_get. - * Both local and remote completion is guaranteed. + * 'REGULAR' variant of dart_put. + * Copy data from local memory into memory referenced by a global pointer. + * When this functions returns, neither local nor remote completion + * is guaranteed. A later flush operation is needed to guarantee + * local and remote completion. * - * \ingroup DartCommuncation - */ -dart_ret_t dart_get_blocking( - void *dest, - dart_gptr_t ptr, - size_t nbytes); -/** - * 'BLOCKING' variant of dart_put. - * Both local and remote completion is guaranteed. + * \param gptr A global pointer determining the target of the put operation. + * \param src The local source buffer to load the data from. + * \param nbytes The number of bytes to transfer. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * - * \ingroup DartCommuncation + * \ingroup DartCommunication */ -dart_ret_t dart_put_blocking( - dart_gptr_t ptr, - const void * src, - size_t nbytes); +dart_ret_t dart_put( + dart_gptr_t gptr, + const void * src, + size_t nbytes); + /** + * Guarantee completion of all outstanding operations involving a segment on a certain unit + * * Guarantees local and remote completion of all pending puts and * gets on a certain memory allocation / window / segment for the - * target unit specified in gptr. -> MPI_Win_flush() + * target unit specified in gptr. + * Similar to \c MPI_Win_flush(). + * + * \param gptr Global pointer identifying the segment and unit to complete outstanding operations for. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * - * \ingroup DartCommuncation + * \ingroup DartCommunication */ dart_ret_t dart_flush( dart_gptr_t gptr); /** + * Guarantee completion of all outstanding operations involving a segment on all units + * * Guarantees local and remote completion of all pending puts and * gets on a certain memory allocation / window / segment for all - * target units. -> MPI_Win_flush_all() + * target units. + * Similar to \c MPI_Win_flush_all(). + * + * \param gptr Global pointer identifying the segment to complete outstanding operations for. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * - * \ingroup DartCommuncation + * \ingroup DartCommunication */ dart_ret_t dart_flush_all( dart_gptr_t gptr); /** + * Guarantee local completion of all outstanding operations involving a segment on a certain unit + * * Guarantees local completion of all pending puts and * gets on a certain memory allocation / window / segment for the * target unit specified in gptr. -> MPI_Win_flush_local() * - * \ingroup DartCommuncation + * \param gptr Global pointer identifying the segment and unit to complete outstanding operations for. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_flush_local( dart_gptr_t gptr); /** + * Guarantee completion of all outstanding operations involving a segment on all units + * * Guarantees local completion of all pending puts and * gets on a certain memory allocation / window / segment for the * all units. -> MPI_Win_flush_local_all() * - * \ingroup DartCommuncation + * \param gptr Global pointer identifying the segment to complete outstanding operations for. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_flush_local_all( dart_gptr_t gptr); + +/** \} */ + +/** + * \name Non-blocking single-sided communication operations using handles + * The handle can be used to wait for a specific operation to complete using \c wait functions. + */ + +/** \{ */ + +/** + * Handle returned by \c dart_get_handle and the like used to wait for a specific + * operation to complete using \c dart_wait etc. + */ +typedef struct dart_handle_struct * dart_handle_t; + +/** + * 'HANDLE' variant of dart_get. + * Neither local nor remote completion is guaranteed. A later + * dart_wait*() call or a fence/flush operation is needed to guarantee + * completion. + * + * \param dest Local target memory to store the data. + * \param gptr Global pointer being the source of the data transfer. + * \param nbytes The number of bytes to transfer. + * \param[out] handle Pointer to DART handle to instantiate for later use with \c dart_wait, \c dart_wait_all etc. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication + */ +dart_ret_t dart_get_handle( + void * dest, + dart_gptr_t gptr, + size_t nbytes, + dart_handle_t * handle); + +/** + * 'HANDLE' variant of dart_put. + * Neither local nor remote completion is guaranteed. A later + * dart_wait*() call or a fence/flush operation is needed to guarantee + * completion. + * + * \param gptr Global pointer being the target of the data transfer. + * \param src Local source memory to transfer data from. + * \param nbytes The number of bytes to transfer. + * \param[out] handle Pointer to DART handle to instantiate for later use with \c dart_wait, \c dart_wait_all etc. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication + */ +dart_ret_t dart_put_handle( + dart_gptr_t gptr, + const void * src, + size_t nbytes, + dart_handle_t * handle); + /** * Wait for the local and remote completion of an operation. * - * \ingroup DartCommuncation + * \param handle The handle of the operation to wait for. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ + dart_ret_t dart_wait( dart_handle_t handle); /** - * Wait for the local and remote completion of operationis. + * Wait for the local and remote completion of operations. + * + * \param handles Array of handles of operations to wait for. + * \param n Number of \c handles to wait for. * - * \ingroup DartCommuncation + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_waitall( - dart_handle_t *handle, + dart_handle_t *handles, size_t n); /** * Wait for the local completion of an operation. * - * \ingroup DartCommuncation + * \param handle Handle of an operations to wait for. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_wait_local( dart_handle_t handle); + /** * Wait for the local completion of operations. * - * \ingroup DartCommuncation + * \param handles Array of handles of operations to wait for. + * \param n Number of \c handles to wait for. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_waitall_local( - dart_handle_t *handle, + dart_handle_t *handles, size_t n); /** - * Wait for the local completion of an operation. + * Test for the local completion of an operation. + * + * \param handle The handle of an operation to test for completion. + * \param[out] result \c True if the operation has completed. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * - * \ingroup DartCommuncation + * \ingroup DartCommunication */ dart_ret_t dart_test_local( dart_handle_t handle, int32_t *result); + /** - * Wait for the local completion of operations. + * Test for the local completion of operations. + * + * \param handles Array of handles of operations to test for completion. + * \param n Number of \c handles to test for completion. + * \param[out] result \c True if all operations have completed. * - * \ingroup DartCommuncation + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication */ dart_ret_t dart_testall_local( - dart_handle_t *handle, + dart_handle_t *handles, size_t n, int32_t *result); +/** \} */ + +/** + * \name Blocking single-sided communication operations + * These operations will block until completion of put and get is guaranteed. + */ + +/** \{ */ + +/** + * 'BLOCKING' variant of dart_get. + * Both local and remote completion is guaranteed. + * + * \param dest Local target memory to store the data. + * \param gptr Global pointer being the source of the data transfer. + * \param nbytes The number of bytes to transfer. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication + */ +dart_ret_t dart_get_blocking( + void *dest, + dart_gptr_t gptr, + size_t nbytes); + +/** + * 'BLOCKING' variant of dart_put. + * Both local and remote completion is guaranteed. + * + * \param gptr Global pointer being the target of the data transfer. + * \param src Local source memory to transfer data from. + * \param nbytes The number of bytes to transfer. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * + * \ingroup DartCommunication + */ +dart_ret_t dart_put_blocking( + dart_gptr_t gptr, + const void * src, + size_t nbytes); + +/** \} */ +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_OFF +/** \endcond */ #ifdef __cplusplus } diff --git a/dart-if/v3.2/include/dash/dart/if/dart_globmem.h b/dart-if/v3.2/include/dash/dart/if/dart_globmem.h index 7fde11f60..539d4c752 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart_globmem.h +++ b/dart-if/v3.2/include/dash/dart/if/dart_globmem.h @@ -16,7 +16,9 @@ extern "C" { #endif +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_ON +/** \endcond */ /* --- DART global pointers --- @@ -64,15 +66,19 @@ extern "C" { */ /** - * Global pointer type. + * DART Global pointer type. * * \ingroup DartGlobMem */ typedef struct { + /** The unit holding the memory element */ dart_unit_t unitid; + /** The segment ID of the allocation */ int16_t segid; + /** Reserved */ uint16_t flags; + /** Absolute address or relative offset */ union { uint64_t offset; @@ -80,6 +86,10 @@ typedef struct } addr_or_offs; } dart_gptr_t; +/** + * A NULL global pointer + * \ingroup DartGlobMem + */ #ifdef __cplusplus #define DART_GPTR_NULL (dart_gptr_t { -1, 0, 0, { 0 } }) #else @@ -89,10 +99,20 @@ typedef struct .addr_or_offs.offset = 0 })) #endif +/** + * Test for NULL global pointer + * + * \ingroup DartGlobMem + */ #define DART_GPTR_ISNULL(gptr_) \ (gptr_.unitid<0 && gptr_.segid==0 && \ gptr_.flags==0 && gptr_.addr_or_offs.addr==0) +/** + * Compare two global pointers + * + * \ingroup DartGlobMem + */ #define DART_GPTR_EQUAL(gptr1_, gptr2_ ) \ ((gptr1_.unitid == gptr2_.unitid) && \ (gptr1_.segid == gptr2_.segid) && \ @@ -106,6 +126,11 @@ typedef struct * gptr. I.e., if the global pointer has affinity to the local unit, * return the local memory address. * + * \param gptr Global pointer + * \param[out] addr Pointer to a pointer that will hold the local address if the \c gptr points to a local memory element. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * * \ingroup DartGlobMem */ dart_ret_t dart_gptr_getaddr(const dart_gptr_t gptr, void **addr); @@ -114,6 +139,11 @@ dart_ret_t dart_gptr_getaddr(const dart_gptr_t gptr, void **addr); * Set the local memory address for the specified global pointer such * the the specified address. * + * \param gptr Global pointer + * \param addr Pointer holding the local address to set in \c gptr. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * * \ingroup DartGlobMem */ dart_ret_t dart_gptr_setaddr(dart_gptr_t *gptr, void *addr); @@ -121,6 +151,10 @@ dart_ret_t dart_gptr_setaddr(dart_gptr_t *gptr, void *addr); /** * Add 'offs' to the address specified by the global pointer * + * \param gptr Global pointer + * \param offs Offset by which to increment \c gptr + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * \ingroup DartGlobMem */ dart_ret_t dart_gptr_incaddr(dart_gptr_t *gptr, int32_t offs); @@ -128,44 +162,63 @@ dart_ret_t dart_gptr_incaddr(dart_gptr_t *gptr, int32_t offs); /** * Set the unit information for the specified global pointer. * + * \param gptr Global Pointer + * \param unit The unit to set in \c gptr + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * \ingroup DartGlobMem */ -dart_ret_t dart_gptr_setunit(dart_gptr_t *gptr, dart_unit_t); +dart_ret_t dart_gptr_setunit(dart_gptr_t *gptr, dart_unit_t unit); /** * Allocates nbytes of memory in the global address space of the calling * unit and returns a global pointer to it. * This is *not* a collective function. * + * \param nbytes The number of bytes to allocate. + * \param[out] gptr Global Pointer to hold the allocation + * + * \todo Does dart_memalloc really allocate in _global_ memory? + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * * \ingroup DartGlobMem */ dart_ret_t dart_memalloc(size_t nbytes, dart_gptr_t *gptr); /** * Frees memory in the global address space allocated by a previous call - * of \c dart_memalloc. + * of \ref dart_memalloc. * This is *not* a collective function. * + * \param gptr Global pointer to the memory allocation to free + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * \ingroup DartGlobMem */ dart_ret_t dart_memfree(dart_gptr_t gptr); /** - * Collective function on the specified team to allocate nbytes of + * Collective function on the specified team to allocate \c nbytes of * memory in each unit's global address space with a type_disp as the * local disposition (size in bytes) of the allocated type. - * The allocated memory is team-aligned (i.e., a global pointer to + * The allocated memory is team-aligned, i.e., a global pointer to * anywhere in the allocation can easily be formed locally. The global - * pointer to the beginning of the allocation is is returned in gptr on - * each participating unit. I.e., Each participating unit has to call - * dart_team_memalloc_aligned with the same specification of teamid and - * nbytes. Each unit will receive the a global pointer to the beginning - * of the allocation (on unit 0) in gptr. + * pointer to the beginning of the allocation is returned in \c gptr on + * each participating unit. Each participating unit has to call + * \c dart_team_memalloc_aligned with the same specification of \c teamid and + * \c nbytes. Each unit will receive the a global pointer to the beginning + * of the allocation (on unit 0) in \c gptr. * Accessibility of memory allocated with this function is limited to * those units that are part of the team allocating the memory. I.e., * if unit X was not part of the team that allocated the memory M, then - * X may not be able to acces a memory location in M. + * X may not be able to access a memory location in M. + * + * \param teamid The team participating in the collective memory allocation + * \param nbytes The number of bytes to allocate per unit + * \param[out] gptr Global pointer to store information on the allocation * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. * \ingroup DartGlobMem */ dart_ret_t dart_team_memalloc_aligned( @@ -173,40 +226,85 @@ dart_ret_t dart_team_memalloc_aligned( size_t nbytes, dart_gptr_t * gptr); -dart_ret_t dart_team_memfree(dart_team_t teamid, dart_gptr_t gptr); +/** + * Collective function to free global memory previously allocated + * using \ref dart_team_memalloc_aligned. + * After this operation, the global pointer should not be used in any + * communication unless re-used in another allocation. + * 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 + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGlobMem + */ +dart_ret_t dart_team_memfree( + dart_team_t teamid, + dart_gptr_t gptr); /** - * Collective function similar to dart_team_memalloc_aligned() but on + * Collective function similar to \ref dart_team_memalloc_aligned but on * previously externally allocated memory. * Does not perform any memory allocation. * + * \param teamid The team to participate in the collective operation. + * \param nbytes The number of bytes already allocated in \c addr. + * \param addr Pointer to pre-allocated memory to be registered. + * \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. + * + * \see dart_team_memalloc_aligned * \ingroup DartGlobMem */ -dart_ret_t dart_team_memregister_aligned(dart_team_t teamid, - size_t nbytes, - void *addr, dart_gptr_t *gptr); +dart_ret_t dart_team_memregister_aligned( + dart_team_t teamid, + size_t nbytes, + void *addr, + dart_gptr_t *gptr); /** * Attaches external memory previously allocated by the user. * Does not perform any memory allocation. * + * \param teamid The team to participate in the collective operation. + * \param nbytes The number of bytes already allocated in \c addr. + * \param addr Pointer to pre-allocated memory to be registered. + * \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. + * * \ingroup DartGlobMem */ -dart_ret_t dart_team_memregister(dart_team_t teamid, - size_t nbytes, - void *addr, dart_gptr_t *gptr); +dart_ret_t dart_team_memregister( + dart_team_t teamid, + size_t nbytes, + void *addr, + dart_gptr_t *gptr); /** * Collective function similar to dart_team_memfree() but on previously * externally allocated memory. * Does not perform any memory de-allocation. * + * \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. + * + * \see dart_team_memregister + * \see dart_team_memregister_aligned * \ingroup DartGlobMem */ dart_ret_t dart_team_memderegister(dart_team_t teamid, dart_gptr_t gptr); +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_OFF +/** \endcond */ #ifdef __cplusplus } diff --git a/dart-if/v3.2/include/dash/dart/if/dart_initialization.h b/dart-if/v3.2/include/dash/dart/if/dart_initialization.h index 44138130e..178425a44 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart_initialization.h +++ b/dart-if/v3.2/include/dash/dart/if/dart_initialization.h @@ -4,9 +4,11 @@ #include "dart_types.h" /** - * \file dart_init.h + * \file dart_initialization.h + * + * \brief Initialization and finalization of the DASH runtime backend. No other DART function may be called before \see dart_init() or after + * \see dart_exit(). * - * Initializationk and finalization of the DASH runtime backend. */ /** @@ -17,33 +19,43 @@ extern "C" { #endif +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_ON +/** \endcond */ /** - * Initialize the DART runtime + * \brief Initialize the DART runtime + * + * \param argc Pointer to the number of command line arguments. + * \param argv Pointer to the array of command line arguments. * - * No other DART function may be called before dart_init() or after - * dart_exit(). + * \return \c DART_OK on sucess or an error code from \see dart_ret_t otherwise. * * \ingroup DartInitialization */ dart_ret_t dart_init(int *argc, char ***argv); /** - * Finalize the DASH runtime. + * \brief Finalize the DASH runtime. + * + * \return \c DART_OK on sucess or an error code from \c dart_ret_t otherwise. * * \ingroup DartInitialization */ dart_ret_t dart_exit(); /** - * Whether the DASH runtime has been initialized. + * \brief Whether the DASH runtime has been initialized. + * + * \return 0 if DART has not been initialized or has been shut down already, >0 otherwise. * * \ingroup DartInitialization */ char dart_initialized(); +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_OFF +/** \endcond */ #ifdef __cplusplus } diff --git a/dart-if/v3.2/include/dash/dart/if/dart_locality.h b/dart-if/v3.2/include/dash/dart/if/dart_locality.h index 8bce55226..1db774af3 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart_locality.h +++ b/dart-if/v3.2/include/dash/dart/if/dart_locality.h @@ -19,7 +19,9 @@ extern "C" { #endif +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_ON +/** \endcond */ /** * Initialize information of the specified team. @@ -184,7 +186,9 @@ dart_ret_t dart_unit_locality( dart_unit_t unit, dart_unit_locality_t ** loc); +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_OFF +/** \endcond */ #ifdef __cplusplus } /* extern "C" */ diff --git a/dart-if/v3.2/include/dash/dart/if/dart_synchronization.h b/dart-if/v3.2/include/dash/dart/if/dart_synchronization.h index 547b8e19c..59c6cef84 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart_synchronization.h +++ b/dart-if/v3.2/include/dash/dart/if/dart_synchronization.h @@ -1,30 +1,90 @@ #ifndef DART_SYNCHRONIZATION_H_INCLUDED #define DART_SYNCHRONIZATION_H_INCLUDED +/** + * \file dart_synchronization.h + * + * \brief Synchronization primitives for mutual exclusion of units. + * + */ + + +/** + * \defgroup DartSync Synchronization primitives for mutual exclusion of units. + * \ingroup DartInterface + */ + #ifdef __cplusplus extern "C" { #endif +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_ON +/** \endcond */ +/** + * Lock type to ensure mutual exclusion among units in a team. + * \ingroup DartSync + */ typedef struct dart_lock_struct *dart_lock_t; +/** + * Collective operation to initialize a the \c lock object. + * + * \param teamid Team this lock is used for. + * \param lock The lock to initialize. + * + * \return \c DART_OK on sucess or an error code from \see dart_ret_t otherwise. + * \ingroup DartSync + */ dart_ret_t dart_team_lock_init(dart_team_t teamid, dart_lock_t* lock); +/** + * Free 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 \see dart_ret_t otherwise. + * \ingroup DartSync + */ dart_ret_t dart_team_lock_free(dart_team_t teamid, dart_lock_t* lock); -/* blocking call */ +/** + * Block until the \c lock was acquired. + * + * \param lock The lock to acquire + * \return \c DART_OK on sucess or an error code from \see dart_ret_t otherwise. + * \ingroup DartSync + */ dart_ret_t dart_lock_acquire(dart_lock_t lock); +/** + * Try to acquire the lock and return immediately. + * + * \param lock The lock to acquire + * \param[out] result \c True if the lock was successfully acquired, false otherwise. + * + * \return \c DART_OK on success or an error code from \see dart_ret_t otherwise. + * \ingroup DartSync + */ dart_ret_t dart_lock_try_acquire(dart_lock_t lock, int32_t *result); +/** + * Release the lock acquired through \ref dart_lock_acquire or \ref dart_lock_try_acquire. + * + * \param lock The lock to release. + * \return \c DART_OK on sucess or an error code from \see dart_ret_t otherwise. + * \ingroup DartSync + */ dart_ret_t dart_lock_release(dart_lock_t lock); +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_OFF +/** \endcond */ #ifdef __cplusplus } diff --git a/dart-if/v3.2/include/dash/dart/if/dart_team_group.h b/dart-if/v3.2/include/dash/dart/if/dart_team_group.h index ce4592ad7..78af3fbbd 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart_team_group.h +++ b/dart-if/v3.2/include/dash/dart/if/dart_team_group.h @@ -3,101 +3,210 @@ #include "dart_types.h" + +/** + * \file dart_team_group.h + * + * Routines for managing groups of units and to form teams. + * + * DART groups are objects with local meaning only. They are + * essentially objects representing sets of units, out of which later + * teams can be formed. The operations to manipulate groups are local + * (and cheap). The operations to create teams are collective and can + * be expensive. + * + * CLARIFICATION: A group does need to keep it's member units in a + * *ascending* order, i.e., a call to \ref dart_group_getmembers will + * return the list of member units in ascending order. Similarly, a + * call to \ref dart_group_split will split the group according to an + * ascending ordering of the member units. + * + * CLARIFICATION: Groups and teams interact in two ways. First, when a + * team is created and a group specification is passed in. Second, + * through the call \ref dart_team_get_group, where the group associated + * with the team can be derived. In both cases, the group *always* + * contains the global Unit IDs, i.e., the unit IDs relative to + * \ref DART_TEAM_ALL. + * + */ + +/** + * \defgroup DartGroupTeam Management of groups and teams + * \ingroup DartInterface + */ + #ifdef __cplusplus extern "C" { #endif +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_ON +/** \endcond */ -/* - DART groups are objects with local meaning only. They are - essentially objects representing sets of units, out of which later - teams can be formed. The operations to manipulate groups are local - (and cheap). The operations to create teams are collective and can - be expensive. - - CLARIFICATION: A group does need to keep it's member units in a - *ascending* order. I.e., a call to dart_group_getmembers() will - return the list of member units in ascending order. Similarly, a - call to dart_group_split() will split the group according to an - ascending ordering of the member units. - - CLARIFICATION: Groups and teams interact in two ways. First, when a - team is created and a group specification is passed in. Second, - through the call dart_team_get_group(), where the group associated - with the team can be derived. In both cases, the group *always* - contains the global Unit IDs (i.e., the unit IDs relative to - DART_TEAM_ALL). +/** + * DART groups are represented by an opaque struct \c dart_group_struct + * + * \ingroup DartGroupTeam */ - -/* DART groups are represented by an opaque struct dart_group_struct */ typedef struct dart_group_struct dart_group_t; -/* - dart_group_init must be called before any other function on the - group object, dart_group_fini reclaims resources that might be - associated with the group (if any). -*/ +/** + * Initialize a DART group object. + * Must be called before any other function on the group object. + * + * \param group Pointer to a group to be initialized. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_init(dart_group_t *group); + +/** + * Reclaim resources that might be associated with the group. + * + * \param group Pointer to a group to be finalized. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_fini(dart_group_t *group); -/* make a copy of the group */ +/** + * Create a copy of the group + * + * \param gin Pointer to a group to be copied. + * \param gout Pointer to the target group object. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_copy(const dart_group_t *gin, dart_group_t *gout); -/* set union */ +/** + * Creation a union of the two groups + * + * \param g1 Pointer to the first group to join. + * \param g2 Pointer to the second group to join. + * \param gout Pointer to the target group object. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_union(const dart_group_t *g1, const dart_group_t *g2, dart_group_t *gout); -/* set intersection */ +/** + * Create an intersection of the two groups + * + * \param g1 Pointer to the first group to intersect. + * \param g2 Pointer to the second group to intersect. + * \param gout Pointer to the target group object. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_intersect(const dart_group_t *g1, const dart_group_t *g2, dart_group_t *gout); -/* add a member */ +/** + * Add a member to the group. + * + * \param unitid Unit to add to group \c g. + * \param g Pointer to the target group object. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_addmember(dart_group_t *g, dart_unit_t unitid); -/* delete a member */ +/** + * Remove a member from the group. + * + * \param unitid Unit to remove from group \c g. + * \param g Pointer to the target group object. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_delmember(dart_group_t *g, dart_unit_t unitid); -/* test if unitid is a member */ +/** + * Test if a unit is a member of the group. + * + * \param unitid Unit to test in group \c g. + * \param g Pointer to the target group object. + * \param[out] ismember True if \c unitid is member of group \c g, false otherwise. + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_ismember(const dart_group_t *g, dart_unit_t unitid, int32_t *ismember); -/* determine the size of the group */ +/** + * Determine the size of the group. + * + * \param g Pointer to the group object. + * \param[out] size The number of units in the group. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_size(const dart_group_t *g, size_t *size); -/* get all the members of the group, unitids must be large enough - to hold dart_group_size() members */ +/** + * Get all the members of the group, \c unitids must be large enough + * to hold the number of members returned by \ref dart_group_size. + * + * \param g Pointer to the group object. + * \param[out] unitids An array large enough to hold the number of units as returned by \ref dart_group_size. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_getmembers(const dart_group_t *g, dart_unit_t *unitids); -/* split the group into \c n groups of approx. same size, - \c gout must be an array of \c dart_group_t objects of size at least \c n. -*/ +/** + * Split the group into \c n groups of approx. the same size, + * \c gout must be an array of \c dart_group_t objects of size at least \c n. + * + * \param g Pointer to the group object. + * \param n The number of groups to split \c g into. + * \param[out] gout An array of at least \c n pointers to the opaque \ref dart_group_t + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_split(const dart_group_t * g, size_t n, dart_group_t ** gout); -/* split the group \c g into \c n groups by the specified locality scope. - For example, a locality split in socket scope creates at least one new - group for every socket containing all units in the original group that - have affinity with the respective socket. - Size of array \c gout must have a capacity of at least \c n - \c dart_group_t objects. +/** + * Split the group \c g into \c n groups by the specified locality scope. + * For example, a locality split in socket scope creates at least one new + * group for every socket containing all units in the original group that + * have affinity with the respective socket. + * Size of array \c gout must have a capacity of at least \c n + * \c dart_group_t objects. + * + * \param g Pointer to the group object. + * \param domain The domain to use for the split. + * \param scope The scope to use for the split. + * \param n The number of groups to split \c g into. + * \param[out] gout An array of at least \c n pointers to the opaque \ref dart_group_t + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam */ dart_ret_t dart_group_locality_split(const dart_group_t * g, dart_domain_locality_t * domain, @@ -105,129 +214,207 @@ dart_ret_t dart_group_locality_split(const dart_group_t * g, size_t n, dart_group_t ** gout); -/* get the size of the opaque object */ +/** + * Get the size of an opaque \ref dart_group_t object. + * + * \param[out] size The size of the opaque \ref dart_group_t object. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_group_sizeof(size_t *size); -/* the default team consisting of all units that comprise - the program */ +/** + * The default team consisting of all units + * that run the application. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ #define DART_TEAM_ALL ((dart_team_t)0) +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_TEAM_NULL ((dart_team_t)-1) +/** \endcond */ -/* get the group associated with the specified team */ +/** + * Query the group associated with the specified team + * + * \param teamid The team to use. + * \param group Pointer to a group object. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_team_get_group(dart_team_t teamid, dart_group_t *group); -/* - Create a new team from the specified group - - This is a collective call: All members of the parent team have to - call this function with an equivalent specification of the new team - to be formed (even those that do not participate in the new - team). Units not participating in the new team may pass a null - pointer for the group specification. - - The returned integer team ID does *not need* to be globally unique. - - However, the following guarantees are made: - - 1) Each member of the new team will receive the same numerical team - ID. - - 2) The team ID of the returned team will be unique with respect to - the parent team. - - 3) If a unit is part of several teams, all these teams will have - different team IDs - - Example: - - DART_TEAM_ALL: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - - Form two sub-teams of equal size (0-4, 5-9): - - dart_team_create(DART_TEAM_ALL, {0,1,2,3,4}) -> TeamID=1 - dart_team_create(DART_TEAM_ALL, {5,6,7,8,9}) -> TeamID=2 - - (1,2 are unique ID's with respect to the parent team (DART_TEAM_ALL) - - Build further sub-teams: - - dart_team_create(1, {0,1,2}) -> TeamID=2 - dart_team_create(1, {3,4}) -> TeamID=3 - - (2,3 are unique with respect to the parent team (1)). +/** + * Create a new team from the specified group + * + * This is a collective call: All members of the parent team have to + * call this function with an equivalent specification of the new team + * to be formed (even those that do not participate in the new + * team). Units not participating in the new team may pass a null + * pointer for the group specification. + * + * The returned integer team ID does *not need* to be globally unique. + * + * However, the following guarantees are made: + * + * 1) Each member of the new team will receive the same numerical team ID. + * 2) The team ID of the returned team will be unique with respect to the parent team. + * 3) If a unit is part of several teams, all these teams will have different team IDs + * + * Example: + * + * DART_TEAM_ALL: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * + * Form two sub-teams of equal size (0-4, 5-9): + * + * dart_team_create(DART_TEAM_ALL, {0,1,2,3,4}) -> TeamID=1 + * dart_team_create(DART_TEAM_ALL, {5,6,7,8,9}) -> TeamID=2 + * + * (1,2 are unique ID's with respect to the parent team (DART_TEAM_ALL) + * + * Build further sub-teams: + * + * dart_team_create(1, {0,1,2}) -> TeamID=2 + * dart_team_create(1, {3,4}) -> TeamID=3 + * + * (2,3 are unique with respect to the parent team (1)). + * + * \param teamid The parent team to use whose units participate in the collective operation. + * \param group The group object to build the new team from. + * \param[out] newteam Will contain the new team ID upon successful return. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam */ dart_ret_t dart_team_create(dart_team_t teamid, const dart_group_t * group, dart_team_t * newteam); -/* Free up resources associated with the specified team */ +/** + * Free up resources associated with the specified team + * + * \param teamid The team to deallocate. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_team_destroy(dart_team_t teamid); -/* return the unit id of the caller in the specified team */ +/** + * Return the unit id of the caller in the specified team. + * + * CLARIFICATION on dart_team_myid(): + * + * dart_team_myid(team) returns the relative ID for the calling unit + * in the specified team( [0...n-1] , where n is the size of team n) + * + * The following guarantees are made with respect to the relationship + * between the global IDs and the local IDs. + * + * Consider the following example: + * + * DART_TEAM_ALL = {0,1,2,3,4,5} + * + * t1 = dart_team_create(DART_TEAM_ALL, {4,2,0}} + * + * Global ID | ID in t1 (V1) | ID in t1 (V2) + * --------------------------------------------- + * 0 | 0 | 2 + * 1 | not a member | not a member + * 2 | 1 | 1 + * 3 | not a member | not a member + * 4 | 2 | 0 + * 5 | not a member | not a member + * + * The order as in V1 is guaranteed (I.e., the unit with ID 0 is the + * member with the smallest global ID, regardless of the order in + * which the members are specified in the group spec. + * + * RATIONALE: SPMD code often diverges based on rank/unit ID. It will + * be useful to know the new master (local ID 0) of a newly created + * team before actually creating it.x + * + * \param teamid The team for which the unit ID should be determined. + * \param[out] myid The unit ID of the calling unit in the respective team. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_team_myid(dart_team_t teamid, dart_unit_t *myid); -/* CLARIFICATION on dart_team_myid(): - - dart_team_myid(team) returns the relative ID for the calling unit - in the specified team( [0...n-1] , where n is the size of team n) - - The following guarantees are made with respect to the relationship - between the global IDs and the local IDs. - - Consider the following example: - - DART_TEAM_ALL = {0,1,2,3,4,5} - - t1 = dart_team_create(DART_TEAM_ALL, {4,2,0}} - - Global ID | ID in t1 (V1) | ID in t1 (V2) - --------------------------------------------- - 0 | 0 | 2 - 1 | not a member | not a member - 2 | 1 | 1 - 3 | not a member | not a member - 4 | 2 | 0 - 5 | not a member | not a member - - The order as in V1 is guaranteed (I.e., the unit with ID 0 is the - member with the smallest global ID, regardless of the order in - which the members are specified in the group spec. - - RATIONALE: SPMD code often diverges based on rank/unit ID. It will - be useful to know the new master (local ID 0) of a newly created - team before actually creating it.x - -*/ - -/* return the size of the specified team */ +/** + * Return the size of the specified team. + * + * \param teamid The team for which the size should be determined. + * \param[out] size The size of the team. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_team_size(dart_team_t teamid, size_t *size); -/* shorthand for id and size in the default team DART_TEAM_ALL */ +/** + * Return the id in the default team \ref DART_TEAM_ALL + * + * \param[out] myid The global unit ID of the calling unit. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_myid(dart_unit_t *myid); -dart_ret_t dart_size(size_t *size); - -/* convert between local and global unit IDs +/** + * Return the size of the default team \ref DART_TEAM_ALL + * + * \param[out] size The size of the team. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ +dart_ret_t dart_size(size_t *size); - local means the ID with respect to the specified team - global means the ID with respect to DART_TEAM_ALL - these calls are *not* collective calls on the specified teams -*/ +/** + * Convert from a local to a global unit ID + * + * \c local means the ID with respect to the specified team whereas + * \c global means the ID with respect to \ref DART_TEAM_ALL + * + * This call is *not collective* on the specified team. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_team_unit_l2g(dart_team_t team, dart_unit_t localid, dart_unit_t *globalid); +/** + * Convert from a global to a local unit ID + * + * \c local means the ID with respect to the specified team whereas + * \c global means the ID with respect to \ref DART_TEAM_ALL. + * + * This call is *not collective* on the specified team. + * + * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise. + * \ingroup DartGroupTeam + */ dart_ret_t dart_team_unit_g2l(dart_team_t team, dart_unit_t globalid, dart_unit_t *localid); +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_OFF +/** \endcond */ #ifdef __cplusplus } diff --git a/dart-if/v3.2/include/dash/dart/if/dart_types.h b/dart-if/v3.2/include/dash/dart/if/dart_types.h index 337b58070..5c2f1b998 100644 --- a/dart-if/v3.2/include/dash/dart/if/dart_types.h +++ b/dart-if/v3.2/include/dash/dart/if/dart_types.h @@ -18,45 +18,68 @@ extern "C" { #endif +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_ON +/** \endcond */ /** - * Return values of functions in the DART interface. + * \brief Return values of functions in the DART interface. * * \ingroup DartTypes */ -typedef enum { - DART_OK = 0, - DART_PENDING = 1, - DART_ERR_INVAL = 2, - DART_ERR_NOTFOUND = 3, - DART_ERR_NOTINIT = 4, - DART_ERR_OTHER = 999 +typedef enum +{ + /** Signals success */ + DART_OK = 0, + /** An operation is still pending */ + DART_PENDING = 1, + /** Invalid operation or parameters */ + DART_ERR_INVAL = 2, + /** Missing data encountered */ + DART_ERR_NOTFOUND = 3, + /** DART has not been initialized */ + DART_ERR_NOTINIT = 4, + /** Unspecified error */ + DART_ERR_OTHER = 999 } dart_ret_t; /** + * \brief Operations to be used for certain RMA and collective operations. * \ingroup DartTypes */ -typedef enum { - DART_OP_UNDEFINED = 0, - DART_OP_MIN, - DART_OP_MAX, - DART_OP_SUM, - DART_OP_PROD, - DART_OP_BAND, - DART_OP_LAND, - DART_OP_BOR, - DART_OP_LOR, - DART_OP_BXOR, - DART_OP_LXOR +typedef enum +{ + /** Undefined, do not use */ + DART_OP_UNDEFINED = 0, + /** Minimum */ + DART_OP_MIN, + /** Maximum */ + DART_OP_MAX, + /** Summation */ + DART_OP_SUM, + /** Product */ + DART_OP_PROD, + /** Binary AND */ + DART_OP_BAND, + /** Logical AND */ + DART_OP_LAND, + /** Binary OR */ + DART_OP_BOR, + /** Logical OR */ + DART_OP_LOR, + /** Binary XOR */ + DART_OP_BXOR, + /** Logical XOR */ + DART_OP_LXOR } dart_operation_t; /** - * Raw data types supported by the DART interface. + * \brief Raw data types supported by the DART interface. * * \ingroup DartTypes */ -typedef enum { +typedef enum +{ DART_TYPE_UNDEFINED = 0, DART_TYPE_BYTE, DART_TYPE_SHORT, @@ -70,27 +93,31 @@ typedef enum { } dart_datatype_t; /** + * \brief Data type for storing a unit ID * \ingroup DartTypes */ typedef int32_t dart_unit_t; /** + * \brief Data type for storing a team ID * \ingroup DartTypes */ typedef int32_t dart_team_t; /** + * \brief Undefined unit ID. * \ingroup DartTypes */ #define DART_UNDEFINED_UNIT_ID ((dart_unit_t)(-1)) /** + * \brief Undefined team ID. * \ingroup DartTypes */ #define DART_UNDEFINED_TEAM_ID ((dart_team_t)(-1)) /** - * Scopes of locality domains. + * \brief Scopes of locality domains. * * Enum values are ordered by scope level in the locality hierarchy. * Consequently, the comparison \c (scope_a > scope_b) is valid @@ -139,11 +166,18 @@ typedef enum } dart_locality_scope_t; +/** Maximum size of a host name string in \ref dart_hwinfo_t */ #define DART_LOCALITY_HOST_MAX_SIZE ((int)(30)) +/** Maximum size of a domain tag string in \ref dart_hwinfo_t */ #define DART_LOCALITY_DOMAIN_TAG_MAX_SIZE ((int)(32)) +/** Maximum number of domain scopes in \ref dart_hwinfo_t */ #define DART_LOCALITY_MAX_DOMAIN_SCOPES ((int)(12)) +/** Maximum size of a domain tag string in \ref dart_hwinfo_t + * \todo Unused? */ #define DART_LOCALITY_UNIT_MAX_CPUS ((int)(64)) +/** Maximum number of NUMA domains supported */ #define DART_LOCALITY_MAX_NUMA_ID ((int)(16)) +/** Maximum number of cache levels supported in \ref dart_hwinfo_t */ #define DART_LOCALITY_MAX_CACHE_LEVELS ((int)( 5)) typedef struct { @@ -485,7 +519,9 @@ typedef struct } dart_config_t; +/** \cond DART_HIDDEN_SYMBOLS */ #define DART_INTERFACE_OFF +/** \endcond */ #ifdef __cplusplus }