expose task::ready!

[yoshuawuyts]

Export async_std::task::ready!. Thanks!

[taiki-e]

I believe you forgot to push the changes.

[ghost]

Instead of re-exporting the macro from futures, why not reimplement it? :) That way we're less reliant on the futures crate and besides, the implementation is fairly small anyway:

#[macro_export]
macro_rules! ready {
    ($e:expr $(,)?) => {
        match $e {
            ::std::task::Poll::Ready(t) => t,
            ::std::task::Poll::Pending => return ::std::task::Poll::Pending,
        }
    };
}

As for the placement of the macro, I wonder if we should just put it in the root module? That's what the standard library does with its macros - they're all in the root module and re-exported from the prelude.

I believe that's for historical reasons because at Rust 1.0 it was not possible to place macros in arbitrary modules and they had to be in the crate root (they weren't even importable!), but this convention has kind of stuck and now all new macros still get added there.

We already have one such macro placed into root, async_std::task_local, but I believe uses will never import it manually and will instead get it from the prelude.

[yoshuawuyts]

@stjepang that's exactly what I did in the first pass at this, and the only way I got it to work was by re-exporting it from an external module.

I mean: we should probably create async-macros anyway, but I figured for now I'd just go with the easiest path which is to re-export the futures macro.

[ghost]

If we're going to add the ready macro, I think I'd be most comfortable with placing it into async_std rather than async_std::task and then also re-exporting it into async_std::prelude.

By the way, another benefit of not re-exporting stuff from the futures crate is that we can write better docs for it. The macro currently has very basic docs and we could write a nice doc example there.

[yoshuawuyts]

@stjepang we probably shouldn't name it ready then. How about poll_ready?

There's recent precedent for exposing submodule macros in std now too I believe; Alex recently had something on this. I'll ping him about it.

[yoshuawuyts]

@stjepang another thought: what are we going to do about {join!,try_join!,select!,try_select!}? I'd argue they shouldn't be top-level constructs either, but probably live under future::*. If that is the case, then having task::ready! would be similar.

The other option for them is to change their naming to be future_try_join or something, but that feels worse than future::try_join. I think if we angle it from there it makes more sense to expose these macros from their respective submodules.

[yoshuawuyts]

Now that #187 and #208 are out, this patch has also been migrated to use async-macros (with docs we can manage to our liking).

@stjepang how do you feel about the way macros are laid out now?

[yoshuawuyts]

We now have stream::join as module-level macro and marked as unstable. I think it should be okay to merge this to let people try this out. Thanks!