stream-unconsume

Poll stream partially and get emitted items back! Sometimes it is useful to let someone poll you stream but be able to get it back as if it was never polled. To do so, this crate provides function remember, that, given stream, returns tuple of future and stream. You can move returned stream to any function, losing it, but, when it gets dropped, future, returned from remember, is resolved with new stream that provides all items that was consumed from original stream, as well as the rest of this stream, so you can use it as if you never poll original stream.

You may specify any type to be used as buffer, as long as it implements IntoIterator<Item=Source::Item> and Push<Source::Item>, where Source is the type of stream you want to unconsume. There is convenience function remember_vec, to use Vec as buffer backend (other backends may be LinkedList, VecDeque and so on). We use Push instead of, say, PushBack, to let users ignore order if they wish. For example, consider if you collect stream to HashSet. If you do that reducing stream, you will skip repeating elements right when they arrive. However, if you use our remember_vec function, StreamBuffer will keep all these repeating elements, consuming memory, to let you just drop them when you get your stream back. Note, that Push will add elements using such methods, that, if backend collection preserver insertion order (Vec, but not i.e HashSet), iteration over this collection will be in insert order too. In other words, if you use LinkedList, Push will perform push_back, not push_front as you may expect. Note: Rust doesn't guarantee that Drop is ever called, so you may need to use timeout when you await returned future, otherwise you will wait for it's resolve forever!

Current Version: 0.3.0

License: MIT OR Apache-2.0