From cc823dbdb21c747f465d6fd79c33f860eaf18c86 Mon Sep 17 00:00:00 2001
From: Mladen Ivkovic <mladen.ivkovic@hotmail.com>
Date: Wed, 24 Feb 2021 11:17:56 +0000
Subject: [PATCH] added task lock RTD documentation

---
 doc/RTD/source/Task/index.rst |  1 +
 doc/RTD/source/Task/locks.rst | 65 +++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 doc/RTD/source/Task/locks.rst

diff --git a/doc/RTD/source/Task/index.rst b/doc/RTD/source/Task/index.rst
index 9844210889..2a7882ece0 100644
--- a/doc/RTD/source/Task/index.rst
+++ b/doc/RTD/source/Task/index.rst
@@ -21,3 +21,4 @@ Everything is described in :ref:`Analysis_Tools`.
    adding_your_own
    adding_your_own_neighbour_loop
    adding_to_dependency_plotting_tool
+   locks
diff --git a/doc/RTD/source/Task/locks.rst b/doc/RTD/source/Task/locks.rst
new file mode 100644
index 0000000000..5da48146d9
--- /dev/null
+++ b/doc/RTD/source/Task/locks.rst
@@ -0,0 +1,65 @@
+.. locks
+   Mladen Ivkovic Feb 2021
+
+.. _task_locks:
+.. highlight:: c
+
+
+Task Locks
+=============
+
+Swift doesn't only deal with dependencies, but with data conflicts as
+well.  We can't have two independent tasks working on the same data
+concurrently, even if the tasks have no dependencies between them.
+For this reason, each task locks the data it works on when it begins,
+and unlocks the data again once it's finished. Data here refers to the
+particle (gas, gravity, stars,...) content of a cell as well as of the
+hierarchy of cells in the tree at levels closer to the root that.  By
+default, it is assumed that the task is doing work on hydro
+particles. If your task requires other particle types, you will need
+to specify that in ``src/task.c``. Suppose you have implemented a task
+with type ``task_type_new`` that requires both stars and hydro
+particles: ::
+
+
+    /**
+     * @brief Try to lock the cells associated with this task.
+     *
+     * @param t the #task.
+     */
+    int task_lock(struct task *t) {
+
+      const enum task_types type = t->type;
+      const enum task_subtypes subtype = t->subtype;
+      struct cell *ci = t->ci, *cj = t->cj;
+
+      switch (type) {
+        /* lots of stuff */
+
+        case task_type_new:
+
+          /* is the data locked already? */
+          if (ci->hydro.hold || ci->stars.hold) return 0;
+
+          /* if it's not locked already, lock first particle type (hydro)
+           * if something locked it in the meantime, exit with failure. */
+          if (cell_locktree(ci) != 0) return 0;
+
+          /* if it's not locked already, lock first particle type (stars)
+           * if something locked it in the meantime, first unlock what you
+           * locked, and then exit with failure. */
+          if (cell_slocktree(ci) != 0) {
+            cell_unlocktree(ci);
+            return 0;
+          }
+
+      /* lots of other stuff */
+      }
+
+      /* lots of other stuff */
+
+    }
+
+
+
+Similarly, don't forget to write your unlocking routines in ``task_unlock()`` !
-- 
GitLab