Add try_from constructor

[eholk]

This gives a version that does not panic if the future does not fit which allows programs to recover, such as by boxing the future instead.

[eholk]

An alternative that I'll mention for discussion here is to have this return Result<Self, (StackFutureError, F)>, where StackFutureError is something like:

enum StackFutureError {
    BadAlignment { required: usize, available: usize },
    TooSmall { required: usize, available: usize },
}

That would give a lot more information, but I'm not sure it's useful.

I opted for returning just F because most of the time that's going to be what you want and it avoids having to unpack a tuple on failure cases. The new implementation of from shows how to use this and that you can still find the required size and alignment pretty easily using things like mem::size_of_val.

That said, changing this would be semver-breaking in the future, so it's probably better to discuss which way we want to go now.

[daprilik]

I think this is reasonable.

Tangentially related: as discussed offline, it should be possible to sidestep the alignment panic entirely through the use of something like https://docs.rs/elain/0.3.0/elain/

[eholk]

I was thinking about the alignment issue some more, and one problem is that the alignment on StackFuture needs to be compatible with all futures it might wrap, the same way it needs to be at least as large as all futures it might wrap. This means the alignment would have to become part of the type, so instead of StackFuture<T, STACK_SIZE> we'd have StackFuture<T, STACK_SIZE, ALIGNMENT>. The elain crate would let us actually implement that, but this seems like a pretty big ergonomic hit to fix a problem we haven't seen in practice yet.

If we add the fallback-on-box path (which I'm hopefully going to get done this afternoon), that does give us another path here too: we can box the future if the alignment of the future isn't compatible with the StackFuture. That'd be a behavior change, since mismatched alignment would no longer be a panic, but I don't think that's technically semver breaking.

[daprilik]

LGTM, aside from the potential semver hazard and some doc nits

[daprilik]

I think this is reasonable.

Tangentially related: as discussed offline, it should be possible to sidestep the alignment panic entirely through the use of something like https://docs.rs/elain/0.3.0/elain/