Diamond flow

[ftaiolivista]

I think the documentation must include a note on the diamond flow and how xstream manage it, something like an explanation of atomic updates of flyd.

As well described by @staltz in this answer would be best to avoid diamond shaped stream graph:

But if you can't or won't change the flow shape I think is important to know how it works.

If the forking stream (a) is a MemoryStream no problem, every branch will be executed.

If the forking stream is a simple Stream keep reading...

First, you have to know precedence of execution well described in this Staltz post.

Second I found important to know that the behavior is different if the forking stream (a) is completed or not completed.

If it's completed every branch is executed:

You will get ( --a-b-d-| and then --a-c-d-| )

If (a) is not completed you will get only the first branch ( --a-b-d- )

I think this happens because when the second branch attaches the listener to the completed, forked stream, make it restart. If the forked stream is already started (not completed) the second branch listener is added but it does not receive the event, which is already consumed by the first branch listener. Can anyone confirm this behavior and if it's ok to rely on it?

This clarifies #282

Playground here

[staltz]

Hi @ftaiolivista, I agree it would be helpful to have documentation that describes diamonds and why/how to avoid them. Perhaps you could start by contributing this content to the Wiki? The wiki should be open for edits from anyone. Then, I'm glad to iterate over there, and when it's in good shape, merge in as a PR into the readme docs.