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 | 22 +++++++++++++++------- include/odp/api/spec/init.h | 3 +++ 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/doc/glossary.adoc b/doc/glossary.adoc index 2c0de24..8d77f24 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,19 @@ 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 ignored. + This parameter is only meaningful on OSes which do not support process + hierarchy. It is nevertheless recommended to set the value of this + parameter correctly in all cases for portability. + 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..343735e 100644 --- a/include/odp/api/spec/init.h +++ b/include/odp/api/spec/init.h @@ -234,6 +234,9 @@ 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 + * ignored as all ODP threads have to be descendant of their ODP + * instantiation process. * * @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