Cleanup "local" terminology

[Dan Bonachea]

Currently we use the term "local" with several distinct, incompatible meanings:

1. a global pointer is local() means the referenced object is load/store "addressable". This is also used in the definition of the local team
2. local completion means the initiator's source buffers in an rput are "done"
3. To talk about the local rank receiving indication of local completion

Overloading this term is confusing.

[Former user]

1. Alternatives to local and example of renaming: is_local(), local(), local_team()

   • addressable: is_addressable(), address(), addressable_team()
   • downcastable: is_downcastable(), downcast(), downcastable_team()
   • native: is_native(), native(), native_team()
   • near: is_near(), near(), near_team()

2. Source completion would probably be better than local since it accurately reflects that just the data can be reclaimed, not necessarily that participation from the local rank (bullet 3) is no longer required.

3. This feels like the right use of local.

   • This includes dist_id::local/when_local()

[Dan Bonachea]

I don't claim to know the right terminology answer for UPC++, but for reference here's how it's used in UPC (and correcting a possible misstatement of mine on our call yesterday):

In the UPC spec, the term "local" is not used as a dynamic property - it is a static typing property on pointers. In particular:

pointer-to-local: a pointer whose referenced type is not a shared type.

ie a pointer-to-local is a regular C pointer (as opposed to a pointer-to-shared, which is basically global_ptr<>).

In UPC a pointer-to-local can point to any of:

1. private memory (eg stack, C malloc() heap etc)
2. shared memory with affinity to this thread (eg after a downcast)
3. shared memory with affinity to a supernode peer (after using the optional castability library <upc_castable.h>)

UPC's only affinity query on pointer-to-shared is size_t upc_threadof(shared void *ptr):

The upc_threadof function returns the index of the thread that has affinity to the shared object pointed to by ptr.
If ptr is a null pointer-to-shared, the function returns 0.

In UPC the question "is this pointer-to-shared local?" is malformed, as it's analogous to asking "is this pointer-to-int a pointer-to-double?"

Conversion from pointer-to-shared to pointer-to-local is accomplished via linguistic cast, but only for pointer-to-shared referencing an object with affinity to the casting thread:

If a non-null pointer-to-shared is cast to a pointer-to-local and the affinity of any byte comprising the pointed-to shared object is not to the current thread, the result is undefined.
If a null pointer-to-shared is cast to a pointer-to-local, the result is a null pointer.

Downcasting pointer-to-shared referencing an object with affinity to a supernode peer is accomplished via the optional castability library <upc_castable.h>.

The main benefit of UPC's formulation with "local" as a static type property is it gives us a concise term to mean "pointer in the base language to something that is load/store accessible". But UPC is a parallel language with a distributed type system to specify, so typing issues come up more often than they do in specifying a library interface for UPC++.

[Former user]

Will rename dist_object use of "local" to "here".

Will grep for all occurrences of "local" spec-wide and replace with something like "initiating" or "calling" rank etc where appropriate.

[Former user]

Every occurence of "local" has been eyeballed. Uses meaning "this rank" were reworded to be "current rank" etc. dist_object API changed form "local" to "here".