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
