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