[embind] Add return value policy option for function bindings.

[brendandahl]

This enables C++ function bindings to explicitly control what happens
to an object when returned to JS via BindingType::toWireType. The new
polices are: default(no policy), take_ownership, and reference. The
polices are further explained in the updated documentation.

To support the polices BindingType::toWireType now uses tag dispatching
to allow specialization for each of the return policies. Custom
BindingTypes that do not want to specialize each option can use the
return_value_policy::default_tag which will match all the policies.

Note: this is the framework for further work on improving class property
bindings and allowing more idiomatic JS.

[kripken]

I do not understand what this means. We use the copy constructor, but then what happens to the object? There is no C++ code for it to live in, so it seems like RAII would immediately clean it up..?

[brendandahl]

The copy is a new allocation, so JS gets a pointer and is then responsible for deleting the object. The value/reference that the new object was created from will be automatically deleted by C++.

I'll reword this comment and add some more detail.

[kripken]

Hmm, even with the new text I'm confused here. This is probably my own fault 😄 But say we have a function that returns by value,

Object getObject() { .. }

What is, effectively, the bindings code for that? The text here says the copy constructor is called, so I am imagining

void* bind_getObject() {
  Object copy = getObject(); // copy constructor occurs here during the `=` operation
  ...
}

And somehow in the ... we transfer ownership to JS. But how does copy not end up collected by C++ when that scope ends?

To put my question another way, how can you call the copy constructor without opting into automatic memory management?

[brendandahl]

The copy constructor is explicitly called with a new. e.g. the code for the above would be:

void* bind_getObject() {
  return new Object(getObject());
}

Or in terms of the embind, that happens in the toWireType function here.

[kripken]

Ah, thanks, so it's a raw new that uses the copy constructor. Makes sense to me now.

[kripken]

The approach, docs and tests lgtm. I can't say I can easily follow the C++ template magic, but it looks generally ok to me.

cc @RReverser who may be interested in this.

[kripken]

To make sure I understand, this is a necessary change because this is non-copyable, and the default return value policy would copy?

[brendandahl]

Missed this comment. Yes that's correct. This will be a breaking change, though at least the compiler will catch it and I think it's pretty uncommon.