Repository files navigation

Rhine is a library for synchronous and asynchronous Functional Reactive Programming (FRP).It separates the aspects of clocking, scheduling and resamplingfrom each other, and ensures clock-safety on the type level.

Confused because some examples from the article don't work anymore?As a big simplification and breaking change,explicit schedules were removed in version 1.0.For an overview of the required changes, seethis page.

Complex reactive programs often process data at different rates.For example, games, GUIs and media applicationsmay output audio and video signals, or receiveuser input at unpredictable times.Coordinating these different rates is a hard problem in general.If not enough care is taken, buffer underruns and overflows, space and time leaks,accidental synchronisation of independent sub-systems,and concurrency issues, such as deadlocks, may all occur.

Rhine tackles these problems by annotatingthe signal processing components with clocks,which hold the information when data will beinput, processed and output.Different components of the signal networkwill become active at different times, or workat different rates. If components running under different clocks need to communicate, ithas to be decided when each component becomesactive ("scheduling"), and how data istransferred between the different rates ("resampling").Rhine separates all these aspects from eachother, and from the individual signal processing of each subsystem.It offers a flexible API to all of them and implements severalreusable standard solutions. In the placeswhere these aspects need to intertwine, typingconstraints on clocks come into effect, enforcing clock safety.

A typical example,which can be run ascd rhine-examples/ && cabal run Demonstration,(or using nix flakes withnix develop followedcabal run Demonstration),would be:

--| Create a simple message containing the time stamp since initialisation,--   for each tick of the clock.--   Since 'createMessage' works for arbitrary clocks (and doesn't need further input data),--   it is a 'Behaviour'.--   @time@ is the 'TimeDomain' of any clock used to sample,--   and it needs to be constrained in order for time differences--   to have a 'Show' instance.  createMessage:: (Monadm,Show (Difftime))=>String->BehaviourmtimeString  createMessage str=   timeInfoOf sinceInit>-> arrshow>-> arr (("Clock"++ str++" has ticked at:")++)--| Output a message /every second/ (= every 1000 milliseconds).--   Let us assume we want to assure that 'printEverySecond'--   is only called every second,--   then we constrain its type signature with the clock @Millisecond 1000@.printEverySecond::Showa=>ClSFIO (Millisecond1000)a()  printEverySecond= arrMClprint--| Specialise 'createMessage' to a specific clock.ms500::ClSFIO (Millisecond500)()String  ms500= createMessage"500 MS"ms1200::ClSFIO (Millisecond1200)()String  ms1200= createMessage"1200 MS"--| Create messages every 500 ms and every 1200 ms,--   collecting all of them in a list,--   which is output every second.main::IO()  main= flow$    ms500@@ waitClock--  a Rhine = a ClSF in the context of a Clock|@|--  compose 2 Rhines in parallel    ms1200@@ waitClock--  a Rhine at a different clock>-- collect-->--  buffer results from both Rhines into a list    printEverySecond@@ waitClock--  the final Rhine--| Uncomment the following for a type error (the clocks don't match):-- typeError = ms500 >>> printEverySecond

• rhine/: The main library, which is also mirrored on hackage.
• rhine-gloss/: A wrapper library togloss, a functional OpenGL library.
• rhine-bayes/: A library for stochastic processes and online machine learning, usingmonad-bayes.
• rhine-examples/: Different examples as a starting point to learn Rhine.

The best way to learn about Rhine is currently thearticleRhine: FRP with Type-Level Clocks.

For a quick reference of the most important concepts,see thecheatsheet.

• stackage
• hackage
• https://github.com/turion/rhine-tutorial: Presentation and tutorial app
• https://github.com/turion/sonnendemo: Demo application

• Why does my blocking code, e.g.arrMCl readLn, behaveerratically?

Clocks must be the only things that block a thread, notClSFs. So for example, you can fix:

arrMClreadLn

by using:

tagS>>> arrread::ClSFIOStdinClock()Int

tagS contains the string that theStdinClock grabbed fromstdin, and only the clock has been allowed to block the thread!

• Can a sampling schedule dynamically change, e.g. depend on a signal?

Yes, for instance you could implement a distance-dependentcollision detector.

• How to handle slow computations, i.e. computations that take longer than the sample rate?

Severalstrategies exist and it depends on your use case.ForFixedStep clocks, it won't matter since the execution of the program isn't tied to a realtime clock.ForClSFs running onUTCTime clocks, you can execute the slow code in a separate thread and coordinate merging the results back into the signal network.

SeeContributing.md for details.

• Rhine usually follows up-to-date GHC versions.
• Contributions are welcome!There are always a few issues labelledhelp needed,in case you're looking for an easy way to get started.
• Rhine is a beginner-friendly Haskell project!Even if you're new to Haskell and FRP, you can contribute.This is a good place to start contributing to open-source projects.Have a look at issues labelledgood first issue.If you have questions, don't hesitate to ask on Github.

• https://github.com/turion/rhine-tutorial: Presentation and tutorial app
• https://github.com/fphh/rhine-ghcjs/:A little browser game written with Rhine andreact-hs,compiles withGHCJS to JavaScript.
• https://github.com/turion/sonnendemo:An interactive simulation with a GUI version and a console version,usingrhine-gloss.