On 20 May 2016 at 05:32, Bill Fischofer <[email protected]> wrote:
> > > On Thu, May 19, 2016 at 7:48 AM, Christophe Milard < > [email protected]> wrote: > >> Making clear which ODP instance a thread is joining >> when calling odp_init_local(). >> >> Signed-off-by: Christophe Milard <[email protected]> >> --- >> 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. >> > > I don't think we need to be making this point both because it is > unnecessary and also because it may not be accurate. Even today this > parameter is used for call validation (pass a bogus value into > odp_init_local() and the call will fail, regardless of where you are in the > process hierarchy). Since it is opaque, tomorrow, or in other > implementations, it may also have other uses known only to the > implementation. > If the API does not say anything more than it says today, and I write a test trying to attach to an ODP instance a completely unrelated process (using the instance defined in the ODP API), the test will fail on the linux-generic ODP implementation. Hence the ODP linux implementation is proven to be incompatible with the ODP specification. If any function parameter defined in the ODP API can freely be interpreted or ignored by any ODP implementation, the API definition becomes useless. Can we at least agree that the API should state that "Other requirements may be defined by the ODP implemention" for this specific instance parameter and the the process hierarchy requirement text (as desribed above) can be applied to the linux generic ODP implementation? Christophe. > > >> + 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). >> > > Again, this is unneeded and potentially inaccurate. > > >> + 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() >> > > API change not needed for reasons cited above in addition to Petri's point > about not changing the API files. > > >> * >> * @param instance Instance handle >> * @param thr_type Thread type >> -- >> 2.5.0 >> >> > _______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
