Dunai is a generalized reactive programming library on top of which other variants like Classic FRP, Arrowized FRP and Reactive Values can be implemented.
Installation • Examples • Documentation • Related projects • Technical information • Contributions • History
-
Intuitive syntax and semantics.
-
Composition of effects via use of different monads and transformers.
-
Isolation of effectful and effect-free reactive functions at type level.
-
Time-free (time is not explicitly included) and time-able (time can be added).
-
Fully extensible.
-
Can be used to implement other FRP libraries/flavors on top.
-
Supports applicative, functional and arrowized style.
-
Programs can be tested with QuickCheck and debugged using Haskell Titan.
To use Dunai, you must have a Haskell compiler installed (GHC). We currently
support GHC versions 7.6.3 to 9.8.1. It likely works with other versions as
well.
On Debian/Ubuntu, both can be installed with:
$ apt-get install ghc cabal-installOn Mac, they can be installed with:
$ brew install ghc cabal-installOnce you have a working set of Haskell tools installed, install Dunai by executing:
$ cabal update
$ cabal install --lib dunaiRunning the following will print the word Success if installation has gone
well, or show an error message otherwise:
$ runhaskell <<< 'import Data.MonadicStreamFunction; main = putStrLn "Success"'
Open a GHCi session and import the main Dunai module:
$ ghci
ghci> import Data.MonadicStreamFunctionAn MSF is a time-varying transformation applied to a series of inputs as they come along, one by one.
Use the primitive arr :: (a -> b) -> MSF m a b to turn any pure function into
an MSF that applies the given function to every input. The function embed :: MSF m a b -> [a] -> m [b] runs an MSF with a series of inputs, collecting the
outputs:
ghci> embed (arr (+1)) [1,2,3,4,5]
[2,3,4,5,6]MSFs can have side effects; hence the m that accompanies the type MSF in
the signatures of arr and embed. The function arrM turns a monadic
function of type a -> m b into an MSF that will constantly apply the
function to each input.
For example, the function print takes a value and prints it to the terminal
(a side effect in the IO monad), producing an empty () output. Elevating or
lifting print into an MSF will turn it into a processor that prints each
input passed to it:
ghci> :type print
print :: Show a => a -> IO ()
ghci> :type arrM print
arrM print :: Show a => MSF IO a ()If we now run that MSF with five inputs, all are printed to the terminal:
ghci> embed (arrM print) [1,2,3,4,5]
1
2
3
4
5
[(), (), (), (), ()]As we can see, after all side effects, embed collects all the outputs, which
GHCi shows at the end.
When we only care about the side effects and not the output list, we can
discard it with Control.Monad.void. (Dunai provides an auxiliary function
embed_ for the same purpose.)
ghci> import Control.Monad (void)
ghci> void $ embed (arrM print) [1,2,3,4,5]
1
2
3
4
5MSFs can be piped into one another with the functions (>>>) or (.), so that
the output of one MSF is fed as input to another MSF at each point:
ghci> void $ embed (arr (+1) >>> arrM print) [1,2,3,4,5]
2
3
4
5
6A monadic computation without arguments can be lifted into an MSF with the
function constM:
ghci> :type getLine
getLine :: IO String
ghci> :type constM getLine
constM getLine :: MSF IO a StringThis MSF will get a line of text from the terminal every time it is called, which we can pipe into an MSF that will print it back.
ghci> void $ embed (constM getLine >>> arrM putStrLn) [(), ()]
What the user types, the computer repeats.
What the user types, the computer repeats.
Once again, the computer repeats.
Once again, the computer repeats.Notice how we did not care about the values in the input list to embed: the
only thing that matters is how many elements it has, which determines how many
times embed will run the MSF.
Simulations can run indefinitely with the function reactimate :: MSF m () () -> m (), which is useful when the input to the MSFs being executed is being
produced by another MSFs, like in the case above with constM getLine
producing inputs consumed by arrM putStrLn:
ghci> reactimate (constM getLine >>> arr reverse >>> arrM putStrLn)
Hello
olleH
Haskell is awesome
emosewa si lleksaH
^CDunai has a very extensive API and supports many programming styles. MSFs are
applicatives, so we can transform them using applicative style, and they are
categories, so they can be piped into one another with Control.Category.(.).
For example, the line above can also be written as:
ghci> reactimate (arrM putStrLn . (reverse <$> constM getLine))which is equivalent to:
ghci> reactimate (arrM putStrLn . fmap reverse . constM getLine)Other writing styles (e.g., arrow notation) are also supported. This versatility makes it possible for you to use the notation you feel most comfortable with.
MSFs are immensely expressive. With MSFs, you can implement stream programming, functional reactive programming (both classic and arrowized), reactive programming, and reactive values, among many others. The real power of MSFs comes from the ability to carry out temporal transformations (e.g., delays), to apply different transformations at different points in time, and to work with different monads. See the documentation below to understand how capable they are.
The best introduction to the fundamentals of Monadic Stream Functions is:
The following papers are also related to MSFs:
-
Fault Tolerant Functional Reactive Programming (extended version)
-
Testing and Debugging Functional Reactive Programming (mirror)
-
Actors Design Patterns and Arrowised FRP. Talk by Diego Alonso Blas, describing Monadic Stream Functions and an encoding in scala.
-
Functional Reactive Programming, Refactored. Original talk describing MSFs. Haskell Symposium 2016.
-
Back to the Future: Time Travel in FRP. Talk describing how to do time transformations in FRP and MSFs. Haskell Symposium 2017.
-
Fault Tolerant Functional Reactive Programming. Talk describing how MSFs can be used to add fault tolerance information. ICFP 2018.
-
Rhine: FRP with Type-level Clocks. Talk describing how MSFs can be extended with clocks. Haskell Symposium 2018.
-
The Bearriver Arcade. Fun arcade games made using Bearriver.
-
Haskanoid. Haskell breakout game implemented using the Functional Reactive Programming library Yampa (compatible with Dunai/Bearriver).
-
ivanperez-keera/Yampa: a full FRP implementation that has been used extensively in academia, open source and industry.
-
turion/rhine: extension of Dunai with type-level clocks and explicit coordination.
-
keera-studios/haskell-titan: an advanced, interactive testing framework with support for step-by-step execution and record-and-replay. Haskell-titan supports connecting to dunai systems via its Yampa-compatible interface library bearriver, via a flag in the libraries
titan-debug-yampaandtitan-record-yampa.
Simpler games will be playable without further optimisations. For example, the game haskanoid works well with Dunai/Bearriver. You can try it with:
$ git clone https://github.com/ivanperez-keera/haskanoid.git
$ cd haskanoid/
$ cabal install -f-wiimote -f-kinect -fbearriverIt uses unaccelerated SDL 1.2, the speed is comparable to Yampa's:
$ haskanoid
Performance report :: Time per frame: 13.88ms, FPS: 72.04610951008645, Total running time: 1447
Performance report :: Time per frame: 16.46ms, FPS: 60.75334143377886, Total running time: 3093
Performance report :: Time per frame: 17.48ms, FPS: 57.20823798627002, Total running time: 4841
Performance report :: Time per frame: 19.56ms, FPS: 51.12474437627812, Total running time: 6797
Performance report :: Time per frame: 19.96ms, FPS: 50.100200400801604, Total running time: 8793
Performance report :: Time per frame: 19.44ms, FPS: 51.440329218106996, Total running time: 10737
It runs almost in constant memory, with about 50% more memory consumption than
with Yampa: 200k for Yampa and 300K for Dunai/Bearriver. (There is very minor
leaking, probably we can fix that with seq.)
We have obtained different figures tracking different modules. In the
paper, we provided figures for the whole
game, but we need to run newer reliable benchmarks including every module and
only definitions from FRP.Yampa, FRP.BearRiver and
Data.MonadicStreamFunction.
Dunai includes some benchmarks as part of the main library. You are encouraged to use them to evaluate your pull requests, and to improve the benchmarks themselves.
If this library helps you, you may want to consider buying the maintainer a cup of coffee.
Discussions
If you have any comments, questions, ideas, or other topics that you think will be of interest to the Dunai community, start a new discussion here. Examples include:
- You've created a new game or application that uses Dunai or BearRiver.
- You've written or found a library that helps use Dunai/BearRiver in a particular domain, or apply it to a specific platform.
- You've written or found a paper that mentions Dunai/BearRiver.
- You have an idea for an extension that will enable writing programs that are not currently possible or convenient to capture.
- You think you've found a bug.
- You want to propose an improvement (e.g., make the code faster or smaller).
- You have a question.
- Something in the documentation, a tutorial or a Dunai / BearRiver / FRP paper is unclear.
- You like the project and want to introduce yourself.
Issues
If a specific change is being proposed (either a new feature or a bug fix), you can open an issue documenting the proposed change here.
If you are unsure about whether your submission should be filed as an issue or as a discussion, file it as a discussion. We can always move it later.
Pull requests
Once we determine that an issue will be addressed, we'll decide who does it and when the change will be added to Dunai. Even if you implement the solution, someone will walk you through the steps to ensure that your submission conforms with our version control process, style guide, etc. More information on our process is included below.
Please, do not just send a PR unless there is an issue for it and someone from the Dunai team has confirmed that you should address it. The PR is very likely to be rejected, and we really want to accept your contributions, so it will make us very sad. Open a discussion / issue first and let us guide you through the process.
This project is split in three parts:
- Dunai: a reactive library that combines monads and arrows.
- BearRiver: Yampa implemented on top of Dunai.
- Examples: ballbounce
- sample applications that work both on traditional Yampa and BearRiver.
Dunai also includes some benchmarks as part of the main library. You are encouraged to use them to evaluate your pull requests, and to improve the benchmarks themselves.
We follow this style guide.
We follow git flow. In addition:
- Please document your commits clearly and separately.
- Always refer to the issue you are fixing in the commit summary line with the
text
Refs #<issue_number>at the end. - If there is no issue for your change, then open an issue first and document what you are trying to achieve/improve/fix.
- Do not address more than one issue per commit or per PR. If two changes are not directly related to one another, they belong in different PRs, issues and commits.
- Document what you did in the respective CHANGELOGs in a separate commit before you send a PR. This commit should be the last one in the PR.
- If your commit pertains to one package only, name the package at the
beginning of the summary line with the syntax
<package_name>: <...rest_of_summary...>. - Make sure your changes conform to the coding style.
See the recent repo history for examples of this process. Using a visual repo
inspection tool like gitk may help.
The versioning model we use is the standard in Haskell packages. Versions have
the format <PUB>.<MAJOR>.<MINOR>(.<PATCH>)? where:
-
<PUB>is just a way to signal important milestones or used for promotional reasons (to indicate a major advancement). A zero on this position has no special meaning. -
<MAJOR>increases on incompatible API changes. -
<MINOR>increases on backwards-compatible changes. -
<PATCH>(optional) increases on small changes that do not affect behavior (e.g., documentation).
This library Dunai was created by Ivan Perez and Manuel Baerenz. It is named after the Dunai (aka. Danube, or Дунай) river, one of the main rivers in Europe, originating in Germany and touching Austria, Slovakia, Hungary, Croatia, Serbia, Romania, Bulgaria, Moldova and Ukraine.
Other FRP libraries, like Yampa and Rhine, are named after rivers. Dunai has been chosen due to the authors' relation with some of the countries it passes through, and knowing that this library has helped unite otherwise very different people from different backgrounds.