Missing documentation for LCOs

[shoshijak]

There are a number of questions and pitfalls concerning LCOs that aren't covered at all in the HPX documentation (http://stellar-group.github.io/hpx/docs/html/), in particular the following:

• return type of .then(...) and of when_all(...) and similar
• the fact that the callable object passed as parameter to .then has to take a future<R> as parameter
• the fact that a function passed to async cannot take references as arguments (it would be nice, not only to state that but also to provide ideas of workarounds)

[hkaiser]

@shoshijak The documentation for the future type can be found here: http://en.cppreference.com/w/cpp/experimental/future

It's only the async overload invoking an action which does not support (lvalue) references or pointers. But this is a for a good reason. Invoking actions implies to do remote operations.

In this context passing a pointer is ambiguous as plain pointers do not allow to infer ownership semantics (who will de-allocate the memory?), also it is unclear how many objects should be transferred (just the one a pointer refers to? is it an array, if yes, what's its size...).

Passing an lvalue-reference to an action implies the intent to change the original value of the object the reference refers to. Should that work remotely? Currently we do not support in/out parameters, so we disabled this.

Please note that you should be able to use pointers and lvalue-references for purely local (non-action) calls to async just fine.

[hkaiser]

@shoshijak Also, we'd be more than happy to accept a patch which adds this information to the docs in a way you would be happy with.