Add MaybeImmediate future

[richard-w]

MaybeImmediate<Fut> wraps a future via FutureExt::maybe_immediate but it can also be constructed directly from a Fut::Output value which is then returned on the first poll without ever creating a Fut. It behaves almost like MaybeDone<Fut> but the first poll after completion will take the output and return it.

This is particularly useful in situations where a function validates inputs and calls another function that returns a future when the input is valid. In case the input is not valid MaybeImmediate can be used to bail out with an error early without having to return a trait object via Box::pin.

For example we'd be able to write this (pseudo-code):

fn validate_then_do_something(inputs: Inputs) -> impl Future<Result<(), ()>> {
  if is_valid(&inputs) {
    do_something(inputs).maybe_immediate()
  } else {
    future::maybe_immediate(Err(()))
  }
}

fn do_something(inputs: Inputs) -> impl Future<Result<(), ()>> {
  // ...
}

instead of

fn validate_then_do_something(inputs: Inputs) -> Pin<Box<dyn Future<Output = Result<(), ()>>> {
  if is_valid(&inputs) {
    Box::pin(do_something(inputs))
  } else {
    Box::pin(std::future::ready(Err(())))
  }
}

fn do_something(inputs: Inputs) -> impl Future<Result<(), ()>> {
  // ...
}

[taiki-e]

Thanks for the PR. To be honest, I don't really understand why this is necessary when we already have MaybeDone.

View changes since this review

[richard-w]

@taiki-e MaybeImmediate, when wrapping a Future<Output = T>, is itself a Future<Output = T> while MaybeDone will always be a Future<Output = ()>.

MaybeDone allows taking the value of its inner Future using a method but it will not itself resolve to that value. This makes MaybeDone only useful in situations where you know that you're dealing with a MaybeDone. It is not really usable as a trait object in particular. Adding MaybeImmediate solves that problem and doesn't break existing users.

If a breaking change is acceptable here then MaybeDone should probably be changed instead.

[rustbot]

☔ The latest upstream changes (possibly #3022) made this pull request unmergeable. Please resolve the merge conflicts.