Improve docs to make it clear grants persist until released

[buzmeg]

Did I miss a way to test if the BBQueue is empty without actually pulling bytes?

If not, was there an architectural reason not to implement is_empty() on a Consumer?

Rationale for is_empty():

Sometimes I may want to check to see if there is something in the queue and then schedule the actual read for later/somewhere else. For example, I may want to set a flag in interrupt context or schedule a DMA sometime later.

Unfortunately, if I have to call read() I have to be ready in case the read comes back with a grant instead of InsufficientSize. Getting that grant to where it needs to be may not be very simple especially if the grant is only the first half of a read cut apart by inversion of the read/write pointers.

Thanks.

[jamesmunns]

Hey! I could implement this, though grants do not do anything when dropped without committing.

For example, this would do exactly what you want:

let data_pending = consumer.read().is_ok();

I'd also accept a PR that implements this directly though, without having to make a "throwaway grant".

[buzmeg]

Oh! So consumer.read() always returns the same thing until release() is executed (or until the producer commits something new)?

Somehow, I missed that. Presumably, that would just let me pull the grant, check it, set the flag, drop the grant, and then let the other thread pull another grant.

Thanks. Sorry about missing that.

[jamesmunns]

Hey @buzmeg, is it okay if I close this? Or would you like to see a change to add an is_empty() feature, or a docs update to make this more clear?

[buzmeg]

@jamesmunns Go ahead and close this. However, the docs/examples definitely need an example that you read() the same data until release().

[jamesmunns]

I'd definitely appreciate a PR if you have a chance! Otherwise I'll leave this open as a reminder.