Add first draft of design document + rearrange modules

[HeinrichApfelmus]

I have begun writing a draft on the design internals of the reactive-banana library. I had always wanted to write this up, as I believe that there are a couple of intricate design issues solved, but have never found the time to do so — until now.

Documenting the internals is useful for understanding and fixing issues such as #228 .

I have also rearranged the modules to follow the "design levels" (low, mid, high) in an attempt to make the edifice easier to understand. The idea is that understanding the implementation of a lower level is not required for understanding the implementation of a higher level.

Question to my dear co-maintainers: As writing will still be slow in the foreseeable future, which areas in the design.md document would you like me to expand on next? Anything that you are particularly interested in or find particularly puzzling?

[ocharles]

Oh, what a terrific idea! I've actually been thinking about setting up a Read the Docs page for reactive-banana, and a design document is one section I'd like to have there (along side more tutorials, a cookbook, etc). I was going to try and write the design document myself, but it's even better if it comes from the source! To plug prior work, my rel8 library uses Read the Docs to provide a comprehensive "Getting Started" document, and it would be great to provide a similar resource for reactive-banana users.

Anything that you are particularly interested in or find particularly puzzling?

I feel quite confident that I understand the internals of reactive-banana from the recent performance work I've been doing, and I think my understanding matches your low/mid/high stratification. My understanding is that at the most primitive level we have a graph of pulses. We enrich this with latches to introduce history, and then we further enrich this to get the lovely API that we give to consumers.

The missing piece of the puzzle to me is observable sharing. I know what it is (at least, in as much as I know data-reify and have read Type-Safe Observable Sharing in Haskell (Gill 09)). What haven't quite formed an understanding of how this is used in reactive-banana, or why it is necessary. Expanding that section would be the highest value to me.

I should also add that I think a design document is useful to more than just implementors. There are unfortunately important operational concerns (or perhaps even abstraction leak?) to users. The main ones that comes to mind are understanding:

• Triggering an evaluation of the event network is synchronous.
• Currently only one event can fire at a time, blocking any other events (though they will eventually fire).
• reactimates and IO from execute occur on the same thread that began network evaluation - this is significant for libraries like OpenGL which can only be called from a single thread.

Perhaps our design document can clarify these subtle points.

[mitchellwrosen]

Looks great so far! I don't have any specific requests for areas to document next.

Speaking of observable sharing, there is a small thread about it in this issue, with an unresolved comment at the bottom: #221

It might be good to circle back at some point before documenting why Cached is the way it is.

[HeinrichApfelmus]

The missing piece of the puzzle to me is observable sharing [..] Expanding that section would be the highest value to me.

Great, thanks! When I'll get around to tackling the next section, it will be the section on observable sharing. 😊

Speaking of observable sharing, there is a small thread about it in this issue, with an unresolved comment at the bottom: #221

Absolutely. I'll get back to that.

There are unfortunately important operational concerns (or perhaps even abstraction leak?) to users. […]

Good points; these are mostly concurrency issues that need to be documented. Overall, I have opted to implement a design that does not introduce any concurrency on its own, but is stable under concurrent use.