Better name for...

[polytypic]

Does someone have an idea for a better name for the hold combinator? See the doc here.

[vasily-kirichenko]

The purpose of this combinator is not clear for me. Could you show/add to the docs an example of its usage?

[polytypic]

In the iOS application I'm working on, I'm using that combinator in various places to basically limit the frequency of updates. Here is a simplified snippet from one such case:

Stream.merge viewChanged (Stream.indefinitely (timeOutMillis 30000))
|> Stream.hold (timeOutMillis 2000)
|> ...

Basically, viewChanged produces an event each time the user changes the view. To update the information displayed to the user, the application needs to poll the backend. So, if the user does nothing, a poll needs to performed anyway to keep the display up to date. However, if the user changes the view, then it is useful to update the view sooner as entirely new items may enter the view, but not immediately, because the interaction usually takes a moment. However, if the user keeps changing the view, it is still useful to refresh the view. The throttle combinator is similar, but it would not allow any updates while the user keeps changing the view.

[vasily-kirichenko]

So, it produces events not more frequently that each 2 seconds, and the latest event is always yielded. Is [sample()](http://reactivex.io/RxJava/javadoc/rx/Observable.html#sample%28long, java.util.concurrent.TimeUnit%29) from Rx do the same?

BTW, it would be great to have such diagrams visually describing how each combinator works.

[vasily-kirichenko]

Or maybe [throttleLast()](http://reactivex.io/RxJava/javadoc/rx/Observable.html#throttleLast%28long, java.util.concurrent.TimeUnit%29) is closer to hold?

I'm struggling to see the difference between the two though.

[polytypic]

Thanks! I was going to say that throttleLast is probably the same operation (as close as possible), but indeed the RxJava documentation is vague enough that there does not seem to be any difference between throttleLast and sample. After eyeballing the documentation for a while, I believe that throttleLast is not the same as hold. The documentation seems to imply that there is a periodic timer inside throttleLast, like with sample. This is not how hold operates. hold only starts the timeout when the underlying stream produces an element. Then the latest element produced by the underlying streams is produced when the timeout fires. Then the process starts over. I find this to be more useful than having a periodic timer that is independent of the underlying stream.

[vasily-kirichenko]

OK, maybe one of these debounce combinators would fit? :)

[vasily-kirichenko]

Yes, [this one](http://reactivex.io/RxJava/javadoc/rx/Observable.html#debounce%28long, java.util.concurrent.TimeUnit%29) seems to fit well. And its nicely named.

[polytypic]

That debounce actually seems to be identical to throttle rather than hold. Note that it says that no events are produced if the source is too fast.

Heh... I must say that I find it interesting that Erik Meijer @headinthebox rants about pull semantics in https://www.youtube.com/watch?v=pOl4E8x3fmw#t=37m48s . Yes, semantics are important, but I have yet to see the semantics of Rx operators specified precisely anywhere. It is clear that the push model breaks if your callbacks don't return in time, so I don't think that the push model can magically make your program "reactive" rather than just "responsive". If you have enough CPU time to handle all events in time, then you can have essentially the same timing properties with the pull model when your consumers eagerly pull all the streams. On the other hand, the pull model directly supports a kind of back pressure in that streams can be lazy.

But, getting back to naming, I think that I might rename throttle as debounce and hold as throttle. (None of the RxJava operations discussed so far seems to have same semantics as hold.) Thanks for the RxJava link, BTW. The .Net Rx documentation online is generally extremely vague as to the precise semantics of the operations.

[polytypic]

Updated: debounce and throttle

[vasily-kirichenko]

Looks good. And the pics are very helpful.

[vasily-kirichenko]

I think it may be a good idea to contrast debounce and throttle to each other in the docs, at least "see also" or elaborate on the difference (no events for too fast source vs guaranteed delayed events).