I found a bind() function in the dist_object test code. I see that bind() has indeed implemented, but not in the spec. We need to bring the two into alignment.
Similarly, several tests are using an unspecified future<T>::operator>>() as shorthand for future<T>::then().
Both of these discrepancies are causing confusion for users, and need to be either added to the spec or excised from the tests and publicly-visible API.
I agree with future >> since it has an equivalent form which is in the spec (then). But why does bind need to be in the spec? Im not saying it doesn't, this just needs to be backed up. It's ok for an implementation to contain unspecified functionality, especially when it's there primarily to support the specified functionality (which bind is). So who's clamoring for a bind that it deserves to be promoted in to the spec? Also what is our policy on unspecified things showing up in tests? I have no problem with that since I see tests as implementation specifics. It's the examples directory which should stay confined to the spec.
I don't know if a bind() interface is justified for the spec or not. For the moment let's assume we don't want that in the spec.
The issue is users who are trying to learn the interface and are reading the tests see the use of unspecified symbols in the upcxx:: namespace and then get confused about what's happening because they cannot find the corresponding documentation.
It seems clearer and cleaner to only put specified, public interfaces in the upcxx:: namespace. Then we have a separate namespace for unspecified internal utilities that exist for purposes like unit testing but are not intended for use by end users and have no documentation or stability guarantee. Eg if the function was named upcxx_internal::bind, there's less potential for confusion, and it makes it very easy to audit client code for places where they might rely upon such unspecified symbols.
On the 9-12 Pagoda meeting, we resolved that internal symbols not intended for end users should be moved out of the top-level upcxx:: namespace, both to prevent name collisions when using namespace upcxx (even though some consider that a poor programming practice), but perhaps more importantly as documentation of which symbols are not intended to be stable/supported public interfaces. We agreed that symbols intended to implement public features which are not yet fully specified (eg serialization) are fine to leave in the namespace for now, although those should be audited once the feature is deployed.
The table of contents (page 4) for the generated Doxygen documentation in issue 36 gives a complete listing of all the functions and types currently in the public upcxx:: namespace. Many of these symbols do not appear in the spec, and most of those do not look like they are ever intended for end users. Examples include: upcxx::bind upcxx::digest upcxx::fast_hash upcxx::nop upcxx::print upcxx::os_env upcxx::parcel_reader upcxx::command_execute upcxx::future1 and many more.
After this release, we should look into cleaning up the public namespace. One possible approach may be to move the entire current implementation into a reserved namespace (eg upcxx_internal), which can probably be accomplished as a mechanical search-and-replace process, and then add a new upcxx namespace that imports each of the public symbols by name and nothing else.
This issue was discussed in the 1/10/18 meeting.
We resolved to use the approach of move the entire implementation to a reserved internal/detail namespace and individually import specified public symbols into a new otherwise-blank upcxx:: namespace.
Brian agreed to do this immediately after the March release, to minimize conflicts with concurrent development.
Mass roll-over of unresolved issues to the next milestone.
This issue was triaged at the 2019-07-24 Pagoda issue meeting and assigned a new milestone.
This was discussed in the 2020-02-12 meeting and deferred to next release milestone.
Mass roll-over of open issues to next release milestone
Resolved by Merge pull request #328 into develop @ 0e5f91c
This issue was discussed in the 1/10/18 meeting.
We resolved to use the approach of move the entire implementation to a reserved internal/detail namespace and individually import specified public symbols into a new otherwise-blank upcxx:: namespace.
Brian agreed to do this immediately after the March release, to minimize conflicts with concurrent development.