Add poll_recv method to Receiver

[jsdw]

This PR Adds a poll_recv() method to the Receiver type. It returns the same Result<T,RecvError> type that the receiver.recv() future returns (hence the name).

This method can be used when defining custom streams that internally make use of async_broadcast and want to know about whether the async_broadcast stream has overflowed or not.

[zeenix]

LGTM otherwise.

[jsdw]

I added an example to poll_recv(), and added an OverflowError so that poll_recv() could be more precise rather than returning a RecvError.

@zeenix what do you reckon? :)

This reminds me that it would be good to document possible errors from this method in a Errors section (as per the conventions).

I wasn't sure what you meant here offhand (I can't see any such sections in the repo)

[zeenix]

I added an example to poll_recv()

Awesome!

and added an OverflowError so that poll_recv() could be more precise rather than returning a RecvError.

Is it worth it? Do we envision any other information going in it other than the count? If not, I'd rather keep things simple and just return the integer. If we need an error type, then we just go with option#1.

This reminds me that it would be good to document possible errors from this method in a Errors section (as per the conventions).

I wasn't sure what you meant here offhand (I can't see any such sections in the repo)

I meant adding a # Error heading in the docs of the method and listing all possible errors it can throw.

[jsdw]

Is it worth it? Do we envision any other information going in it other than the count? If not, I'd rather keep things simple and just return the integer. If we need an error type, then we just go with option#1.

My arguments for keeping OverflowError would be:

• The name of the type makes it clear what it is about (ie an error caused because of overflow)
• It acts like the other errors returned in Results throughout this library, ie it implements Error and Display and can be handled accordingly by libs like anyhow and such.

But happy to go either way if you'd prefer otherwise

I meant adding a # Error heading in the docs of the method and listing all possible errors it can throw.

There are no other Error sections in the library for other functions that return Results, but I did what some of those did and added a bit of text about the error condition. Happy to put that into an # Error section if you like though?

[zeenix]

The name of the type makes it clear what it is about (ie an error caused because of overflow)

It's clear enough since it's the Err variant of a Result. :) The docs would remove any confusion (if there is still some). :)

It acts like the other errors returned in Results throughout this library, ie it implements Error and Display and can be handled accordingly by libs like anyhow and such.

usize also implements Display so that isn't a good argument but Error impl is. I'd be fine with RecvError here based on this argument.

There are no other Error sections in the library for other functions that return Results,

I didn't realize that but just because we've been lazy so far, doesn't mean we should continue to be so. :) Also in other fallible methods, all variants of the returned result type are possible so it's not as important as when returning an Error and not all variants could be possible (which would be the case for RecvError here).

By "convention", I meant the general conversion in the Rust world (I think it's even recommended in the book).

Happy to put that into an # Error section if you like though?

Yes please.

[jsdw]

Done and done!

[zeenix]

Done and done!

You're too efficient. Do it again! 😆

[zeenix]

Almost done. :)

[zeenix]

👍

[zeenix]

@jsdw now if you could just update the PR description, I can squash merge with that as the commit message. 🙏

[niklasad1]

now if you could just update the PR description, I can squash merge with that as the commit message.

@zeenix good to go? :)