Making clear which ODP instance a thread is joining
when calling odp_init_local().

Signed-off-by: Christophe Milard <christophe.mil...@linaro.org>
---
 doc/glossary.adoc           | 24 +++++++++++++++++-------
 include/odp/api/spec/init.h |  4 ++++
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/doc/glossary.adoc b/doc/glossary.adoc
index 2c0de24..209a292 100644
--- a/doc/glossary.adoc
+++ b/doc/glossary.adoc
@@ -10,7 +10,8 @@ control thread::
     operating system house keeping tasks but will be scheduled by it and may
     receive interrupts.
 ODP instantiation process::
-    The process calling `odp_init_global()`, which is probably the
+    The OS "flow of execution" (i.e. OS process or OS thread)
+    calling `odp_init_global()`, which is probably the
     first process which is started when an ODP application is started.
     There is one single such process per ODP instantiation.
 thread::
@@ -19,12 +20,21 @@ thread::
 ODP thread::
     An ODP thread is a flow of execution that belongs to ODP:
     Any "flow of execution" (i.e. OS process or OS thread) calling
-    `odp_init_global()`, or `odp_init_local()` becomes an ODP thread.
-    This definition currently limits the number of ODP instances on a given
-    machine to one. In the future `odp_init_global()` will return something
-    like an ODP instance reference and `odp_init_local()` will take such
-    a reference in parameter, allowing threads to join any running ODP 
instance.
-    Note that, in a Linux environment an ODP thread can be either a Linux
+    `odp_init_local()` becomes an ODP thread.
+    On OSes supporting process hierarchy (e.g. linux), any "flow of execution"
+    calling `odp_init_local()` becomes an ODP thread of the ODP instance whose
+    ODP instantiation process is an ancestor of (or same as) this
+    "flow of execution".
+    This means that on these OSes, all ODP threads are descendant of (or
+    same as) their ODP instantiation process.
+    This also means that on these OSes, the ODP instance passed as
+    `odp_init_local()` parameter is redundant, as the ODP instance the thread
+    belongs to is actually already defined by the process hierarchy.
+    This parameter is only meaningful on OSes which do not support process
+    hierarchy. The instance number should nevertheless be set to the correct
+    value (matching the ancestor ODP instance on OS supporting process
+    hierarchy).
+    Note that, e.g. in a Linux environment, an ODP thread can be either a Linux
     process or a linux thread (i.e. a linux process calling `odp_init_local()`
     will be referred as ODP thread, not ODP process).
 event::
diff --git a/include/odp/api/spec/init.h b/include/odp/api/spec/init.h
index fec6774..7592669 100644
--- a/include/odp/api/spec/init.h
+++ b/include/odp/api/spec/init.h
@@ -234,6 +234,10 @@ int odp_term_global(odp_instance_t instance);
  * All threads must call this function before calling any other ODP API
  * functions. The instance parameter specifies which ODP instance the thread
  * joins. A thread may be simultaneously part of single ODP instance only.
+ * On OSes supporting process hierarchy (e.g linux), this parameter is actually
+ * redundant as all ODP threads have to be descendant of their ODP
+ * instantiation process: In these case, the instance parameter must match the
+ * ODP instance of the ancestor process which called ODP_init_global()
  *
  * @param instance        Instance handle
  * @param thr_type        Thread type
-- 
2.5.0

_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Reply via email to