2016-05-03 21:17:06 +03:00
|
|
|
dejafu [![Build Status][build-status]][build-log]
|
2016-05-03 02:05:29 +03:00
|
|
|
======
|
|
|
|
|
2016-05-03 21:17:06 +03:00
|
|
|
[build-status]: https://travis-ci.org/barrucadu/dejafu.svg?branch=master
|
|
|
|
[build-log]: https://travis-ci.org/barrucadu/dejafu
|
|
|
|
|
2016-05-03 02:05:29 +03:00
|
|
|
> [Déjà Fu is] A martial art in which the user's limbs move in time as
|
|
|
|
> well as space, […] It is best described as "the feeling that you
|
|
|
|
> have been kicked in the head this way before"
|
|
|
|
>
|
|
|
|
> -- Terry Pratchett, Thief of Time
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
- [Installation](#installation)
|
|
|
|
- [Quick start guide](#quick-start-guide)
|
|
|
|
- [Why Déjà Fu?](#why-déjà-fu)
|
|
|
|
- [Contributing](#contributing)
|
|
|
|
- [Release notes](#release-notes)
|
|
|
|
- [Questions, feedback, discussion](#questions-feedback-discussion)
|
|
|
|
- [Bibliography](#bibliography)
|
|
|
|
- **[The website!](http://dejafu.readthedocs.io/)**
|
2016-05-03 02:05:29 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Déjà Fu is a unit-testing library for concurrent Haskell programs.
|
|
|
|
Tests are deterministic and expressive, making it easy and convenient
|
|
|
|
to test your threaded code. Available on [GitHub][], [Hackage][], and
|
|
|
|
[Stackage][].
|
2016-05-03 02:05:29 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
[GitHub]: https://github.com/barrucadu/dejafu
|
|
|
|
[Hackage]: https://hackage.haskell.org/package/dejafu
|
|
|
|
[Stackage]: https://www.stackage.org/package/dejafu
|
2014-12-20 20:32:35 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Features:
|
2016-06-20 23:45:34 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
- An abstraction over the concurrency functionality in `IO`
|
|
|
|
- Deterministic testing of nondeterministic code
|
|
|
|
- Both complete (slower) and incomplete (faster) modes
|
|
|
|
- A unit-testing-like approach to writing test cases
|
|
|
|
- A property-testing-like approach to comparing stateful operations
|
|
|
|
- Testing of potentially nonterminating programs
|
|
|
|
- Integration with [HUnit][] and [tasty][]
|
2015-08-27 15:33:48 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
[HUnit]: https://hackage.haskell.org/package/HUnit
|
|
|
|
[Tasty]: https://hackage.haskell.org/package/tasty
|
2016-04-03 16:26:31 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
There are a few different packages under the Déjà Fu umbrella:
|
2014-12-20 20:32:35 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
| | Version | Summary |
|
|
|
|
| - | ------- | ------- |
|
2017-10-14 07:51:47 +03:00
|
|
|
| [concurrency][h:conc] | 1.2.1.2 | Typeclasses, functions, and data types for concurrency and STM. |
|
2017-10-11 12:34:26 +03:00
|
|
|
| [dejafu][h:dejafu] | 0.9.0.0 | Systematic testing for Haskell concurrency. |
|
|
|
|
| [hunit-dejafu][h:hunit] | 0.7.0.2 | Deja Fu support for the HUnit test framework. |
|
|
|
|
| [tasty-dejafu][h:tasty] | 0.7.0.2 | Deja Fu support for the Tasty test framework. |
|
2015-10-25 19:14:00 +03:00
|
|
|
|
2017-04-07 20:16:08 +03:00
|
|
|
Each package has its own README and CHANGELOG in its subdirectory.
|
2015-10-08 23:50:52 +03:00
|
|
|
|
2016-04-01 18:54:45 +03:00
|
|
|
There is also dejafu-tests, the test suite for dejafu. This is in a
|
|
|
|
separate package due to Cabal being bad with test suite transitive
|
|
|
|
dependencies.
|
|
|
|
|
2016-08-25 19:24:00 +03:00
|
|
|
[h:conc]: https://hackage.haskell.org/package/concurrency
|
|
|
|
[h:dejafu]: https://hackage.haskell.org/package/dejafu
|
|
|
|
[h:hunit]: https://hackage.haskell.org/package/hunit-dejafu
|
|
|
|
[h:tasty]: https://hackage.haskell.org/package/tasty-dejafu
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Everything is on Hackage and Stackage, and the last three major GHC
|
|
|
|
versions (currently 8.2, 8.0, and 7.10) are supported.
|
2016-08-25 19:24:00 +03:00
|
|
|
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Installation
|
|
|
|
------------
|
2016-08-25 19:24:00 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Install from Hackage globally:
|
2016-08-25 19:24:00 +03:00
|
|
|
|
|
|
|
```
|
2017-09-01 16:12:44 +03:00
|
|
|
$ cabal-install dejafu
|
2016-08-25 19:24:00 +03:00
|
|
|
```
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Or add it to your cabal file:
|
2016-08-25 19:24:00 +03:00
|
|
|
|
|
|
|
```
|
2017-09-01 16:12:44 +03:00
|
|
|
build-depends: ...
|
|
|
|
, dejafu
|
2016-08-25 19:24:00 +03:00
|
|
|
```
|
2016-05-03 02:05:29 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Or to your package.yaml:
|
2016-05-03 02:05:29 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
```
|
|
|
|
dependencies:
|
|
|
|
...
|
|
|
|
- dejafu
|
2016-08-25 19:24:00 +03:00
|
|
|
```
|
2016-05-03 02:05:29 +03:00
|
|
|
|
2016-08-25 19:24:00 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Quick start guide
|
|
|
|
-----------------
|
2016-08-25 19:24:00 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Déjà Fu supports unit testing, and comes with a helper function called
|
|
|
|
`autocheck` to look for some common issues. Let's see it in action:
|
2016-08-25 19:24:00 +03:00
|
|
|
|
|
|
|
```haskell
|
2017-09-01 16:12:44 +03:00
|
|
|
import Control.Concurrent.Classy
|
2016-08-25 19:24:00 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
myFunction :: MonadConc m => m String
|
|
|
|
myFunction = do
|
|
|
|
var <- newEmptyMVar
|
|
|
|
fork (putMVar var "hello")
|
|
|
|
fork (putMVar var "world")
|
|
|
|
readMVar var
|
2016-08-25 19:24:00 +03:00
|
|
|
```
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
That `MonadConc` is a typeclass abstraction over concurrency, but
|
|
|
|
we'll get onto that shortly. First, the result of testing:
|
2016-08-25 19:24:00 +03:00
|
|
|
|
|
|
|
```
|
2017-09-01 16:12:44 +03:00
|
|
|
> autocheck myFunction
|
|
|
|
[pass] Never Deadlocks (checked: 12)
|
2016-08-25 19:24:00 +03:00
|
|
|
[pass] No Exceptions (checked: 12)
|
|
|
|
[fail] Consistent Result (checked: 11)
|
2017-09-01 16:12:44 +03:00
|
|
|
"hello" S0----S1-P2-S0--
|
2016-08-25 19:24:00 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
"world" S0----S2--S0-P1-S0-
|
2016-08-25 19:24:00 +03:00
|
|
|
False
|
|
|
|
```
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
There are no deadlocks or uncaught exceptions, which is good; but the
|
|
|
|
program is (as you probably spotted) nondeterministic!
|
2016-05-03 02:05:29 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Along with each result, Déjà Fu gives us a representative execution
|
|
|
|
trace in an abbreviated form. `Sn` means that thread `n` started
|
|
|
|
executing, and `Pn` means that thread `n` pre-empted the previously
|
|
|
|
running thread.
|
2017-08-11 18:08:26 +03:00
|
|
|
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Why Déjà Fu?
|
|
|
|
------------
|
2017-08-11 18:08:26 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Testing concurrent programs is difficult, because in general they are
|
|
|
|
nondeterministic. This leads to people using work-arounds like
|
|
|
|
running their testsuite many thousands of times; or running their
|
|
|
|
testsuite while putting their machine under heavy load.
|
|
|
|
|
|
|
|
These approaches are inadequate for a few reasons:
|
|
|
|
|
|
|
|
- **How many runs is enough?** When you are just hopping to spot a bug
|
|
|
|
by coincidence, how do you know to stop?
|
|
|
|
- **How do you know if you've fixed a bug you saw previously?**
|
|
|
|
Because the scheduler is a black box, you don't know if the
|
|
|
|
previously buggy schedule has been re-run.
|
|
|
|
- **You won't actually get that much scheduling variety!** Operating
|
|
|
|
systems and language runtimes like to run threads for long periods
|
|
|
|
of time, which reduces the variety you get (and so drives up the
|
|
|
|
number of runs you need).
|
|
|
|
|
|
|
|
Déjà Fu addresses these points by offering *complete* testing. You
|
|
|
|
can run a test case and be guaranteed to find all results with some
|
|
|
|
bounds. These bounds can be configured, or even disabled! The
|
|
|
|
underlying approach used is smarter than merely trying all possible
|
|
|
|
executions, and will in general explore the state-space quickly.
|
|
|
|
|
|
|
|
If your test case is just too big for complete testing, there is also
|
|
|
|
a random scheduling mode, which is necessarily *incomplete*. However,
|
|
|
|
Déjà Fu will tend to produce much more schedule variety than just
|
|
|
|
running your test case in `IO` the same number of times, and so bugs
|
|
|
|
will tend to crop up sooner. Furthermore, as you get execution traces
|
|
|
|
out, you can be certain that a bug has been fixed by simply following
|
|
|
|
the trace by eye.
|
2017-08-11 18:08:26 +03:00
|
|
|
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Contributing
|
|
|
|
------------
|
2017-08-11 18:08:26 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
See the CONTRIBUTING.markdown file.
|
2017-08-11 18:08:26 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
**If you'd like to get involved with Déjà Fu**, check out [the
|
2017-10-15 03:27:12 +03:00
|
|
|
"good first issue" label on the issue tracker][beginners].
|
2017-08-11 18:08:26 +03:00
|
|
|
|
2017-10-15 03:27:12 +03:00
|
|
|
[beginners]: https://github.com/barrucadu/dejafu/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
|
2017-08-11 18:08:26 +03:00
|
|
|
|
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Release notes
|
|
|
|
-------------
|
2017-08-11 18:08:26 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
See the CHANGELOG.markdown file.
|
2016-05-03 02:05:29 +03:00
|
|
|
|
2017-04-08 07:39:36 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
Questions, feedback, discussion
|
|
|
|
-------------------------------
|
2016-08-25 19:24:00 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
- For general help talk to me in IRC (barrucadu in #haskell) or shoot
|
|
|
|
me an email (mike@barrucadu.co.uk)
|
|
|
|
- For bugs, issues, or requests, please [file an issue][issues].
|
2017-04-07 20:16:08 +03:00
|
|
|
|
2017-09-01 16:12:44 +03:00
|
|
|
[issues]: https://github.com/barrucadu/dejafu/issues
|
2017-04-07 20:16:08 +03:00
|
|
|
|
|
|
|
|
2016-04-01 18:54:45 +03:00
|
|
|
Bibliography
|
|
|
|
------------
|
|
|
|
|
2016-08-25 19:24:00 +03:00
|
|
|
These libraries wouldn't be possible without prior research, which I
|
|
|
|
mention in the documentation. Haddock comments get the full citation,
|
|
|
|
whereas in-line comments just get the shortened name:
|
2016-04-01 18:54:45 +03:00
|
|
|
|
2016-04-01 19:49:35 +03:00
|
|
|
- [BPOR] *Bounded partial-order reduction*, K. Coons, M. Musuvathi,
|
|
|
|
and K. McKinley (2013)
|
2016-04-01 18:54:45 +03:00
|
|
|
http://research.microsoft.com/pubs/202164/bpor-oopsla-2013.pdf
|
|
|
|
|
2016-04-01 19:49:35 +03:00
|
|
|
- [RDPOR] *Dynamic Partial Order Reduction for Relaxed Memory Models*,
|
|
|
|
N. Zhang, M. Kusano, and C. Wang (2015)
|
|
|
|
http://www.faculty.ece.vt.edu/chaowang/pubDOC/ZhangKW15.pdf
|
|
|
|
|
2016-04-01 18:54:45 +03:00
|
|
|
- [Empirical] *Concurrency Testing Using Schedule Bounding: an
|
|
|
|
Empirical Study*, P. Thompson, A. Donaldson, and A. Betts (2014)
|
|
|
|
http://www.doc.ic.ac.uk/~afd/homepages/papers/pdfs/2014/PPoPP.pdf
|
2016-04-01 18:56:17 +03:00
|
|
|
|
|
|
|
- [RMMVerification] *On the Verification of Programs on Relaxed Memory
|
|
|
|
Models*, A. Linden (2014)
|
|
|
|
https://orbi.ulg.ac.be/bitstream/2268/158670/1/thesis.pdf
|
2016-05-03 02:05:29 +03:00
|
|
|
|
|
|
|
There are also a couple of papers on dejafu itself:
|
|
|
|
|
|
|
|
- *Déjà Fu: A Concurrency Testing Library for Haskell*, M. Walker and
|
|
|
|
C. Runciman (2015)
|
|
|
|
https://www.barrucadu.co.uk/publications/dejafu-hs15.pdf
|
|
|
|
|
|
|
|
This details dejafu-0.1, and was presented at the 2015 Haskell
|
|
|
|
Symposium.
|
|
|
|
|
|
|
|
- *Déjà Fu: A Concurrency Testing Library for Haskell*, M. Walker and
|
|
|
|
C. Runciman (2016)
|
|
|
|
https://www.barrucadu.co.uk/publications/YCS-2016-503.pdf
|
|
|
|
|
|
|
|
This is a more in-depth technical report, written between the
|
|
|
|
dejafu-0.2 and dejafu-0.3 releases.
|