Add arbiter documentation

doc/doxygen/chapters/07data_management.doxy

@@ -329,6 +329,34 @@ value of handle1 or handle2 becomes available first, the corresponding task
 running cl2 will start first. The task running cl1 will however always be run
 before them, and the task running cl3 will always be run after them.
 
+If a lot of tasks use the commute access on the same set of data and a lot of
+them are ready at the same time, it may become interesting to use an arbiter,
+see \ref ConcurrentDataAccess .
+
+\section ConcurrentDataAccess Concurrent Data accesses
+
+When several tasks are ready and will work on several data, StarPU is faced with
+the classical Dining Philosophers problem, and has to determine the order in
+which it will run the tasks.
+
+Data accesses usually use sequential ordering, so data accesses are usually
+already serialized, and thus by default StarPU uses the Dijkstra solution which
+scales very well in terms of overhead: tasks will just acquire data one by one
+by data handle pointer value order.
+
+When sequential ordering is disabled or the ::STARPU_COMMUTE flag is used, there
+may be a lot of concurrent accesses to the same data, and the Dijkstra solution
+gets only poor parallelism, typically in some pathological cases which do happen
+in various applications. In that case, one can use a data access arbiter, which
+implements the classical centralized solution for the Dining Philosophers
+problem. This is more expensive in terms of overhead since it is centralized,
+but it opportunistically gets a lot of parallelism. The centralization can also
+be avoided by using several arbiters, thus separating sets of data for which
+arbitration will be done.  If a task accesses data from different arbiters, it
+will acquire them arbiter by arbiter, in arbiter pointer value order.
+
+See the tests/datawizard/test_arbiter.cpp example.
+
 \section TemporaryBuffers Temporary Buffers
 
 There are two kinds of temporary buffers: temporary data which just pass results

doc/doxygen/chapters/api/data_management.doxy

@@ -21,6 +21,11 @@ StarPU, it is associated to a ::starpu_data_handle_t which keeps track
 of the state of the piece of data over the entire machine, so that we
 can maintain data consistency and locate data replicates for instance.
 
+\typedef starpu_arbiter_t
+\ingroup API_Data_Management
+This is an arbiter, which implements an advanced but centralized management of
+concurrent data accesses, see \ref ConcurrentDataAccess for the details.
+
 \enum starpu_data_access_mode
 \ingroup API_Data_Management
 This datatype describes a data access mode.
@@ -309,4 +314,17 @@ starpu_data_acquire_cb().
 This is the same as starpu_data_release(), except that the data
 will be available on the given memory \p node instead of main memory.
 
+\fn starpu_arbiter_t starpu_arbiter_create(void)
+\ingroup API_Data_Management
+This creates a data access arbiter, see \ref ConcurrentDataAccess for the details
+
+\fn void starpu_data_assign_arbiter(starpu_data_handle_t handle, starpu_arbiter_t arbiter)
+\ingroup API_Data_Management
+This makes accesses to \p handle managed by \p arbiter
+
+\fn void starpu_arbiter_destroy(starpu_arbiter_t arbiter)
+\ingroup API_Data_Management
+This destroys the \p arbiter . This must only be called after all data assigned
+to it have been unregistered.
+
 */