Sup 109 dart threadsafety

CHANGELOG.md

@@ -94,6 +94,9 @@ Features:
         - `dart__base__locality__domain`
         - `dart__base__locality__unit`
 
+Fixes:
+- Added clarification that DART currently does not provide thread-safe access. 
+
 # DASH 0.2.0 (2016-03-03)
 
 ## Build System

dart-if/v3.2/include/dash/dart/if/dart.h

@@ -9,7 +9,8 @@
  * Common C interface of the underlying communication back-end.
  *
  *
- * --- DASH/DART Terminology ---
+ * DASH/DART Terminology
+ * =====================
  *
  * DASH is a realization of the PGAS (partitioned global address space)
  * programming model. Below is an attempt to define some of the
@@ -40,7 +41,7 @@
  * Local/Global/Private/Shared
  * ---------------------------
  *
- * 1) Local and Global:
+ * ### 1) Local and Global: #####
  * The terms local and global are adjectives to describe the address
  * spaces in a DASH program. The local address space of a dash unit is
  * managed by the regular OS mechanisms (malloc, free), and data items
@@ -50,17 +51,17 @@
  * of the global address space. Data items in the global memory are
  * addressed by global pointers provided by the DART runtime.
  *
- * 2) Private and Shared:
+ * ### 2) Private and Shared: ###
  * The adjectives private and shared describe the accessibility of data
  * items in DASH. A shared datum is one that can be accessed by more
  * than one unit (by means of the DART runtime).  A private datum is one
  * that is not shared.
  *
- * 3) Partitions, Affinity, Ownership
+ * ### 3) Partitions, Affinity, Ownership ###
  * ... to be written...
  * idea: we might use the term affinity to express hierarchical locality
  *
- * 4) Team-Alignment and Symmetricity:
+ * ### 4) Team-Alignment and Symmetricity: ###
  * Team-aligned and symmetric are terms describing memory allocations.
  * A memory allocation is symmetric (with respect to a team), if the
  * same amount of memory (in bytes) is allocated by each member of the
@@ -77,8 +78,26 @@
  * A note on thread safety:
  * ------------------------
  *
- * All functions in the DART interface shall be implemented in a thread
- * safe way.
+ * In this release, most of DART's functionality cannot be called from within
+ * multiple threads in parallel. This is especially true for
+ * \ref DartGroupTeam "group and team management" and \ref DartGlobMem "global memory management"
+ * functionality as well as \ref DartCommunication "communication operations".
+ * All exceptions from this rule have been marked accordingly in the documentation.
+ * Improvements to thread-safety of DART are scheduled for the next release.
+ *
+ * Note that this also affects global operations in DASH as they rely on DART functionality.
+ * However, all operations on local data can be considered thread-safe, e.g., `Container.local` or
+ * `Container.lbegin`. The local access operators adhere to the C++ STL thread-safety
+ * rules (see http://en.cppreference.com/w/cpp/container for details).
+ * Thus, the following code is valid:
+ *
+ * \code{.cc}
+dash::Array<int> arr(...);
+#pragma omp parallel for // OK to parallelize since we're working on .local
+for( auto i=0; i<arr.local.size(); i++ ) [
+ arr.local[i]=foo(i);
+}
+ * \endcode
  */
 #ifdef __cplusplus
 extern "C" {

dart-if/v3.2/include/dash/dart/if/dart_communication.h

@@ -7,18 +7,16 @@
 /**
  * \file dart_communication.h
  *
- * \brief A set of basic communication routines in DART.
+ * \defgroup  DartCommunication  Communication routines in DART
+ * \ingroup   DartInterface
+ *
+ * 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 but operates on
  * raw buffers instead. Message sizes are thus specified in bytes.
  */
 
-/**
- * \defgroup  DartCommunication  Communication routines in DART
- * \ingroup   DartInterface
- *
- */
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -57,6 +55,7 @@ dart_ret_t dart_barrier(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_bcast(
@@ -78,6 +77,7 @@ dart_ret_t dart_bcast(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_scatter(
@@ -101,6 +101,7 @@ dart_ret_t dart_scatter(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_gather(
@@ -123,6 +124,7 @@ dart_ret_t dart_gather(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_allgather(
@@ -147,6 +149,7 @@ dart_ret_t dart_allgather(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_allgatherv(
@@ -170,6 +173,7 @@ dart_ret_t dart_allgatherv(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_allreduce(
@@ -185,6 +189,7 @@ dart_ret_t dart_allreduce(
  *
  * \todo Why is this not generic?
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 #if 0
@@ -212,6 +217,7 @@ dart_ret_t dart_reduce(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_accumulate(
@@ -238,6 +244,7 @@ dart_ret_t dart_accumulate(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_fetch_and_op(
@@ -273,6 +280,7 @@ dart_ret_t dart_fetch_and_op(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_get(
@@ -293,6 +301,7 @@ dart_ret_t dart_get(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_put(
@@ -312,6 +321,7 @@ dart_ret_t dart_put(
  * \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.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_flush(
@@ -328,6 +338,7 @@ dart_ret_t dart_flush(
  * \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.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_flush_all(
@@ -344,6 +355,7 @@ dart_ret_t dart_flush_all(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_flush_local(
@@ -360,6 +372,7 @@ dart_ret_t dart_flush_local(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_flush_local_all(
@@ -394,6 +407,7 @@ typedef struct dart_handle_struct * dart_handle_t;
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_get_handle(
@@ -416,6 +430,7 @@ dart_ret_t dart_get_handle(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_put_handle(
@@ -445,6 +460,7 @@ dart_ret_t dart_wait(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_waitall(
@@ -458,6 +474,7 @@ dart_ret_t dart_waitall(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_wait_local(
@@ -471,6 +488,7 @@ dart_ret_t dart_wait_local(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_waitall_local(
@@ -485,6 +503,7 @@ dart_ret_t dart_waitall_local(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_test_local(
@@ -500,6 +519,7 @@ dart_ret_t dart_test_local(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_testall_local(
@@ -526,6 +546,7 @@ dart_ret_t dart_testall_local(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_get_blocking(
@@ -543,6 +564,7 @@ dart_ret_t dart_get_blocking(
  *
  * \return \c DART_OK on success, any other of \ref dart_ret_t otherwise.
  *
+ * \threadsafe_none
  * \ingroup DartCommunication
  */
 dart_ret_t dart_put_blocking(

dart-if/v3.2/include/dash/dart/if/dart_config.h

@@ -6,13 +6,13 @@
 /**
  * \file dart_config.h
  *
- * Interface to access the DART runtime configuration.
- */
-
-/**
  * \defgroup  DartConfig  DART runtime configuration interface
  * \ingroup   DartInterface
+ *
+ * Interface to access the DART runtime configuration.
+ *
  */
+
 #ifdef __cplusplus
 extern "C" {
 #endif