mirror of
https://github.com/barrucadu/dejafu.git
synced 2024-09-11 06:25:45 +03:00
Compare commits
4 Commits
99b654190d
...
bb15fcf4e4
| Author | SHA1 | Date | |
|---|---|---|---|
|
bb15fcf4e4 | ||
|
|
83e391847f | ||
|
|
a4d31bdaaa | ||
|
|
ee99cbb975 |
92
.github/scripts/build-documentation.sh
vendored
Executable file
92
.github/scripts/build-documentation.sh
vendored
Executable file
@ -0,0 +1,92 @@
|
||||
#! /usr/bin/env nix-shell
|
||||
#! nix-shell -I nixpkgs=channel:nixos-23.05 -i bash --packages coreutils mdbook mdbook-admonish python3 virtualenv ghc stack
|
||||
|
||||
set -ex
|
||||
|
||||
OUTPUT_DIR="_site"
|
||||
|
||||
pushd docs
|
||||
mdbook-admonish install
|
||||
popd
|
||||
|
||||
python3 <<'EOF' > docs/src/index.md
|
||||
import sys
|
||||
|
||||
with open("README.markdown") as f:
|
||||
mode = "title"
|
||||
for line in f:
|
||||
line = line.rstrip()
|
||||
if mode == "title":
|
||||
print("Getting Started")
|
||||
mode = "after-title"
|
||||
elif mode == "after-title":
|
||||
if line.startswith("- "):
|
||||
mode = "skip-links"
|
||||
else:
|
||||
print(line)
|
||||
elif mode == "skip-links":
|
||||
if line.startswith("- "):
|
||||
continue
|
||||
else:
|
||||
mode = "pre-version-table"
|
||||
print(line)
|
||||
elif mode == "pre-version-table":
|
||||
print(line)
|
||||
if line.startswith("|"):
|
||||
mode = "version-table"
|
||||
elif mode == "version-table":
|
||||
print(line)
|
||||
if line.startswith("See [the latest package documentation]"):
|
||||
mode = "after-version-table"
|
||||
elif mode == "after-version-table":
|
||||
if line.startswith("["):
|
||||
mode = "pre-contributing"
|
||||
print("")
|
||||
print(line)
|
||||
elif mode == "pre-contributing":
|
||||
if line == "Contributing":
|
||||
mode = "skip-to-bibliography"
|
||||
continue
|
||||
print(line)
|
||||
elif mode == "skip-to-bibliography":
|
||||
if line == "Bibliography":
|
||||
mode = "rest"
|
||||
print(line)
|
||||
else:
|
||||
print(line)
|
||||
|
||||
if mode != "rest":
|
||||
print(f"unexpected mode: {mode}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
EOF
|
||||
|
||||
bash <<'EOF'
|
||||
virtualenv venv
|
||||
source venv/bin/activate
|
||||
pip install "rst-to-myst"
|
||||
|
||||
mkdir -p docs/src/release-notes
|
||||
for package in concurrency dejafu hunit-dejafu tasty-dejafu; do
|
||||
rst2myst convert --no-sphinx "${package}/CHANGELOG.rst"
|
||||
cat "${package}/CHANGELOG.md" | \
|
||||
sed 'sZ{issue}`\([^`]*\)`Z[issue #\1](https://github.com/barrucadu/dejafu/issues/\1)Zg' | \
|
||||
sed 'sZ{pull}`\([^`]*\)`Z[pull request #\1](https://github.com/barrucadu/dejafu/pull/\1)Zg' | \
|
||||
sed 'sZ{tag}`\([^`]*\)`Z[\1](https://github.com/barrucadu/dejafu/releases/tag/\1)Zg' | \
|
||||
sed 'sZ{u}`\([^`]*\)`Z[\1](https://github.com/\1)Zg' | \
|
||||
sed 'sZ{hackage}`\([^`]*\)`Z[\1](https://hackage.haskell.org/package/\1)Zg' > "docs/src/release-notes/${package}.md"
|
||||
rm "${package}/CHANGELOG.md"
|
||||
done
|
||||
|
||||
rm -rf venv
|
||||
EOF
|
||||
|
||||
mdbook build docs
|
||||
mv docs/book "$OUTPUT_DIR"
|
||||
|
||||
stack --no-install-ghc --no-nix --skip-ghc-check --system-ghc haddock concurrency dejafu hunit-dejafu tasty-dejafu
|
||||
rm -rf .stack-work/install/*/*/*/doc/all/
|
||||
mv .stack-work/install/*/*/*/doc/ "$OUTPUT_DIR/packages"
|
||||
|
||||
chmod -c -R +rX "$OUTPUT_DIR" | while read -r line; do
|
||||
echo "::warning title=Invalid file permissions automatically fixed::$line"
|
||||
done
|
||||
17
.github/workflows/ci.yaml
vendored
17
.github/workflows/ci.yaml
vendored
@ -3,6 +3,23 @@ name: Run tests
|
||||
on: pull_request
|
||||
|
||||
jobs:
|
||||
check-docs-site:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Check mdbook-admonish changes are not committed
|
||||
run: |
|
||||
if grep -q "do not edit: managed by \`mdbook-admonish install\`" docs/book.toml; then
|
||||
echo "remove generated mdbook-admonish lines from docs/books.toml" >&2
|
||||
exit 1
|
||||
fi
|
||||
- name: Install nix
|
||||
uses: cachix/install-nix-action@v23
|
||||
with:
|
||||
nix_path: nixpkgs=channel:nixos-23.05
|
||||
- name: Check documentation site builds
|
||||
run: nix-shell ./.github/scripts/build-documentation.sh
|
||||
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
|
||||
51
.github/workflows/deploy-documentation.yml
vendored
Normal file
51
.github/workflows/deploy-documentation.yml
vendored
Normal file
@ -0,0 +1,51 @@
|
||||
name: Deploy documentation site
|
||||
|
||||
on:
|
||||
# Runs on pushes targeting the default branch
|
||||
push:
|
||||
branches: ["master"]
|
||||
|
||||
# Allows you to run this workflow manually from the Actions tab
|
||||
workflow_dispatch:
|
||||
|
||||
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
|
||||
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
# Build job
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v3
|
||||
- name: Install nix
|
||||
uses: cachix/install-nix-action@v23
|
||||
with:
|
||||
nix_path: nixpkgs=channel:nixos-23.05
|
||||
- name: Build
|
||||
run: nix-shell ./.github/scripts/build-documentation.sh
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v2
|
||||
|
||||
# Deployment job
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v2
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@ -4,3 +4,4 @@ dist
|
||||
.stack-work
|
||||
*.tix
|
||||
*.prof
|
||||
_site
|
||||
|
||||
13
.readthedocs.yaml
Normal file
13
.readthedocs.yaml
Normal file
@ -0,0 +1,13 @@
|
||||
version: "2"
|
||||
|
||||
build:
|
||||
os: "ubuntu-22.04"
|
||||
tools:
|
||||
python: "3.10"
|
||||
|
||||
python:
|
||||
install:
|
||||
- requirements: docs/readthedocs/requirements.txt
|
||||
|
||||
sphinx:
|
||||
configuration: docs/readthedocs/source/conf.py
|
||||
@ -14,12 +14,13 @@ dejafu
|
||||
- [Release notes](#release-notes)
|
||||
- [Questions, feedback, discussion](#questions-feedback-discussion)
|
||||
- [Bibliography](#bibliography)
|
||||
- **[The website!](http://dejafu.readthedocs.io/)**
|
||||
- **[The website!](https://dejafu.docs.barrucadu.co.uk/)**
|
||||
|
||||
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][].
|
||||
to test your threaded code.
|
||||
|
||||
Available on [GitHub][], [Hackage][], and [Stackage][].
|
||||
|
||||
[GitHub]: https://github.com/barrucadu/dejafu
|
||||
[Hackage]: https://hackage.haskell.org/package/dejafu
|
||||
@ -47,6 +48,8 @@ There are a few different packages under the Déjà Fu umbrella:
|
||||
| [hunit-dejafu][h:hunit] | 2.0.0.6 | Deja Fu support for the HUnit test framework. |
|
||||
| [tasty-dejafu][h:tasty] | 2.1.0.1 | Deja Fu support for the Tasty test framework. |
|
||||
|
||||
See [the latest package documentation](https://dejafu.docs.barrucadu.co.uk/packages/).
|
||||
|
||||
Each package has its own README and CHANGELOG in its subdirectory.
|
||||
|
||||
There is also dejafu-tests, the test suite for dejafu. This is in a
|
||||
@ -162,7 +165,7 @@ the trace by eye.
|
||||
Contributing
|
||||
------------
|
||||
|
||||
See the "contributing" page on [the website](http://dejafu.readthedocs.io/en/latest/contributing.html).
|
||||
See the "contributing" page on [the website](https://dejafu.docs.barrucadu.co.uk/dev-docs/contributing.html).
|
||||
|
||||
**If you'd like to get involved with Déjà Fu**, check out [the
|
||||
"good first issue" label on the issue tracker][beginners].
|
||||
@ -193,34 +196,33 @@ 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:
|
||||
|
||||
- [BPOR] *Bounded partial-order reduction*, K. Coons, M. Musuvathi,
|
||||
and K. McKinley (2013)
|
||||
http://research.microsoft.com/pubs/202164/bpor-oopsla-2013.pdf
|
||||
- [BPOR] [Bounded partial-order reduction](http://research.microsoft.com/pubs/202164/bpor-oopsla-2013.pdf),
|
||||
K. Coons, M. Musuvathi, and K. McKinley (2013)
|
||||
|
||||
- [RDPOR] *Dynamic Partial Order Reduction for Relaxed Memory Models*,
|
||||
- [RDPOR] [Dynamic Partial Order Reduction for Relaxed Memory Models](http://www.faculty.ece.vt.edu/chaowang/pubDOC/ZhangKW15.pdf),
|
||||
N. Zhang, M. Kusano, and C. Wang (2015)
|
||||
http://www.faculty.ece.vt.edu/chaowang/pubDOC/ZhangKW15.pdf
|
||||
|
||||
- [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
|
||||
- [Empirical] [Concurrency Testing Using Schedule Bounding: an Empirical Study](http://www.doc.ic.ac.uk/~afd/homepages/papers/pdfs/2014/PPoPP.pdf),
|
||||
P. Thompson, A. Donaldson, and A. Betts (2014)
|
||||
|
||||
- [RMMVerification] *On the Verification of Programs on Relaxed Memory
|
||||
Models*, A. Linden (2014)
|
||||
https://orbi.ulg.ac.be/bitstream/2268/158670/1/thesis.pdf
|
||||
- [RMMVerification] [On the Verification of Programs on Relaxed Memory Models](https://orbi.ulg.ac.be/bitstream/2268/158670/1/thesis.pdf),
|
||||
A. Linden (2014)
|
||||
|
||||
There are also a couple of papers on dejafu itself:
|
||||
There are also a few 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
|
||||
- [Déjà Fu: A Concurrency Testing Library for Haskell](https://www.barrucadu.co.uk/publications/dejafu-hs15.pdf),
|
||||
M. Walker and C. Runciman (2015)
|
||||
|
||||
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
|
||||
- [Déjà Fu: A Concurrency Testing Library for Haskell](https://www.barrucadu.co.uk/publications/YCS-2016-503.pdf),
|
||||
M. Walker and C. Runciman (2016)
|
||||
|
||||
This is a more in-depth technical report, written between the
|
||||
dejafu-0.2 and dejafu-0.3 releases.
|
||||
|
||||
- [Revealing Behaviours of Concurrent Functional Programs by Systematic Testing](https://www.barrucadu.co.uk/publications/thesis.pdf),
|
||||
M. Walker (2018)
|
||||
|
||||
This is my Ph.D thesis, which discusses dejafu and my other research projects.
|
||||
|
||||
@ -46,7 +46,7 @@ Fixed
|
||||
|
||||
|
||||
1.11.0.0 (2020-05-14)
|
||||
--------------------
|
||||
---------------------
|
||||
|
||||
* Git: :tag:`concurrency-1.11.0.0`
|
||||
* Hackage: :hackage:`concurrency-1.11.0.0`
|
||||
@ -171,10 +171,10 @@ Added
|
||||
|
||||
* (:issue:`286`) Copy across additions from the :hackage:`stm` package:
|
||||
|
||||
* ``Control.Concurrent.Classy.STM.TQueue.flushTQueue``
|
||||
* ``Control.Concurrent.Classy.STM.TBQueue.flushTBQueue``
|
||||
* ``Control.Concurrent.Classy.STM.TBQueue.lengthTBQueue``
|
||||
* ``Control.Concurrent.Classy.STM.TVar.stateTVar``
|
||||
* ``Control.Concurrent.Classy.STM.TQueue.flushTQueue``
|
||||
* ``Control.Concurrent.Classy.STM.TBQueue.flushTBQueue``
|
||||
* ``Control.Concurrent.Classy.STM.TBQueue.lengthTBQueue``
|
||||
* ``Control.Concurrent.Classy.STM.TVar.stateTVar``
|
||||
|
||||
* (:issue:`287`) The ``Control.Concurrent.Classy.STM.TSem`` module.
|
||||
|
||||
@ -183,10 +183,8 @@ Changed
|
||||
|
||||
* (:issue:`286`) Copy across changes from the :hackage:`stm` package:
|
||||
|
||||
* Make definition of ``readTQueue`` consistent with
|
||||
``readTBQueue``
|
||||
|
||||
* Performance improvements to ``peekTQueue`` and ``peekTBQueue``.
|
||||
* Make definition of ``readTQueue`` consistent with ``readTBQueue``
|
||||
* Performance improvements to ``peekTQueue`` and ``peekTBQueue``.
|
||||
|
||||
Miscellaneous
|
||||
~~~~~~~~~~~~~
|
||||
@ -235,9 +233,9 @@ Miscellaneous
|
||||
|
||||
* GHC 7.10 support is dropped. Dependency lower bounds are:
|
||||
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`array`: 0.5.1
|
||||
* :hackage:`transformers`: 0.5
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`array`: 0.5.1
|
||||
* :hackage:`transformers`: 0.5
|
||||
|
||||
|
||||
1.4.0.2 (2018-03-11)
|
||||
@ -276,8 +274,8 @@ Changed
|
||||
* ``Control.Monad.Conc.Class.peekTicket'`` has a more concrete type,
|
||||
to make deriving newtype instances of ``MonadConc`` possible:
|
||||
|
||||
* Old: ``MonadConc m => proxy m -> Ticket m a -> a``
|
||||
* New: ``MonadConc m => Proxy m -> Ticket m a -> a``
|
||||
* Old: ``MonadConc m => proxy m -> Ticket m a -> a``
|
||||
* New: ``MonadConc m => Proxy m -> Ticket m a -> a``
|
||||
|
||||
|
||||
1.3.0.0 - The Bound Thread Release (2017-12-23)
|
||||
@ -294,21 +292,21 @@ Added
|
||||
|
||||
* (:pull:`145`) Bound thread variants of the ``withAsync`` functions:
|
||||
|
||||
* ``Control.Concurrent.Classy.Async.asyncBound``
|
||||
* ``Control.Concurrent.Classy.Async.asyncBoundN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncBound``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncBoundN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncBound``
|
||||
* ``Control.Concurrent.Classy.Async.asyncBoundN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncBound``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncBoundN``
|
||||
|
||||
* (:pull:`145`) Bound thread functions in ``MonadConc``:
|
||||
|
||||
* ``Control.Monad.Conc.Class.forkOS``
|
||||
* ``Control.Monad.Conc.Class.forkOSN``
|
||||
* ``Control.Monad.Conc.Class.isCurrentThreadBound``
|
||||
* ``Control.Monad.Conc.Class.forkOS``
|
||||
* ``Control.Monad.Conc.Class.forkOSN``
|
||||
* ``Control.Monad.Conc.Class.isCurrentThreadBound``
|
||||
|
||||
* (:pull:`145`) Helper functions for bound threads:
|
||||
|
||||
* ``Control.Monad.Conc.Class.runInBoundThread``
|
||||
* ``Control.Monad.Conc.Class.runInUnboundThread``
|
||||
* ``Control.Monad.Conc.Class.runInBoundThread``
|
||||
* ``Control.Monad.Conc.Class.runInUnboundThread``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
@ -328,10 +326,10 @@ Added
|
||||
|
||||
* (:issue:`148`) Named thread variants of the ``withAsync`` functions:
|
||||
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncOnN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncWithUnmaskN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncOnWithUnmaskN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncOnN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncWithUnmaskN``
|
||||
* ``Control.Concurrent.Classy.Async.withAsyncOnWithUnmaskN``
|
||||
|
||||
|
||||
1.2.2.0 (2017-11-05)
|
||||
@ -345,12 +343,12 @@ Added
|
||||
|
||||
* (:issue:`144`) ``IsConc`` and ``IsSTM`` wrapper types:
|
||||
|
||||
* ``Control.Monad.Conc.Class.IsConc`` (constructor unexported)
|
||||
* ``Control.Monad.Conc.Class.toIsConc``
|
||||
* ``Control.Monad.Conc.Class.fromIsConc``
|
||||
* ``Control.Monad.STM.Class.IsSTM`` (constructor unexported)
|
||||
* ``Control.Monad.STM.Class.toIsSTM``
|
||||
* ``Control.Monad.STM.Class.fromIsSTM``
|
||||
* ``Control.Monad.Conc.Class.IsConc`` (constructor unexported)
|
||||
* ``Control.Monad.Conc.Class.toIsConc``
|
||||
* ``Control.Monad.Conc.Class.fromIsConc``
|
||||
* ``Control.Monad.STM.Class.IsSTM`` (constructor unexported)
|
||||
* ``Control.Monad.STM.Class.toIsSTM``
|
||||
* ``Control.Monad.STM.Class.fromIsSTM``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
@ -398,10 +396,10 @@ Added
|
||||
|
||||
* (:pull:`125`) Named thread variants of the ``async`` functions:
|
||||
|
||||
* ``Control.Concurrent.Classy.Async.asyncN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncOnN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncWithUnmaskN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncOnWithUnmaskN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncOnN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncWithUnmaskN``
|
||||
* ``Control.Concurrent.Classy.Async.asyncOnWithUnmaskN``
|
||||
|
||||
|
||||
1.2.0.0 (2017-09-16)
|
||||
@ -446,12 +444,12 @@ Added
|
||||
|
||||
* Missing functions copied from :hackage:`async`:
|
||||
|
||||
* ``Control.Concurrent.Classy.Async.uninterruptibleCancel``
|
||||
* ``Control.Concurrent.Classy.Async.replicateConcurrently``
|
||||
* ``Control.Concurrent.Classy.Async.concurrently_``
|
||||
* ``Control.Concurrent.Classy.Async.mapConcurrently_``
|
||||
* ``Control.Concurrent.Classy.Async.forConcurrently_``
|
||||
* ``Control.Concurrent.Classy.Async.replicateConcurrently_``
|
||||
* ``Control.Concurrent.Classy.Async.uninterruptibleCancel``
|
||||
* ``Control.Concurrent.Classy.Async.replicateConcurrently``
|
||||
* ``Control.Concurrent.Classy.Async.concurrently_``
|
||||
* ``Control.Concurrent.Classy.Async.mapConcurrently_``
|
||||
* ``Control.Concurrent.Classy.Async.forConcurrently_``
|
||||
* ``Control.Concurrent.Classy.Async.replicateConcurrently_``
|
||||
|
||||
* ``Control.Concurrent.Classy.Async.Concurrently`` has a ``Semigroup``
|
||||
instance when built with :hackage:`base` >= 4.9.
|
||||
|
||||
@ -13,6 +13,7 @@ unreleased
|
||||
Miscellaneous
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
* Update documentation link in ``Test.DejaFu``.
|
||||
* Fix GHC compatibility warning.
|
||||
|
||||
|
||||
@ -139,8 +140,9 @@ Added
|
||||
|
||||
* Thread action constructors for the ``MonadConc`` ``getMaskingState``
|
||||
function:
|
||||
* ``Test.DejaFu.Types.ThreadAction``, ``GetMaskingState``
|
||||
* ``Test.DejaFu.Types.Lookahead``, ``WillGetMaskingState``
|
||||
|
||||
* ``Test.DejaFu.Types.ThreadAction``, ``GetMaskingState``
|
||||
* ``Test.DejaFu.Types.Lookahead``, ``WillGetMaskingState``
|
||||
|
||||
Miscellaneous
|
||||
~~~~~~~~~~~~~
|
||||
@ -194,50 +196,57 @@ Miscellaneous
|
||||
Added
|
||||
~~~~~
|
||||
|
||||
* The ``Test.DejaFu.Types.MonadDejaFu`` typeclass, containing the
|
||||
primitives needed to run a concurrent program. There are instances
|
||||
for:
|
||||
* ``IO``, which is probably the ``MonadConc`` instance people used
|
||||
previously, so there is no breaking change there.
|
||||
* ``CatchT (ST t)``, meaning that concurrent programs can be run
|
||||
without ``IO`` once more.
|
||||
* The ``Test.DejaFu.Types.MonadDejaFu`` typeclass, containing the primitives
|
||||
needed to run a concurrent program. There are instances for:
|
||||
|
||||
* Thread action constructors for ``MonadConc``
|
||||
``supportsBoundThreads`` function:
|
||||
* ``Test.DejaFu.Types.ThreadAction``, ``SupportsBoundThreads``
|
||||
* ``Test.DejaFu.Types.Lookahead``, ``WillSupportsBoundThreads``
|
||||
* ``IO``, which is probably the ``MonadConc`` instance people used previously,
|
||||
so there is no breaking change there.
|
||||
* ``CatchT (ST t)``, meaning that concurrent programs can be run without
|
||||
``IO`` once more.
|
||||
|
||||
* Thread action constructors for ``MonadConc`` ``supportsBoundThreads``
|
||||
function:
|
||||
|
||||
* ``Test.DejaFu.Types.ThreadAction``, ``SupportsBoundThreads``
|
||||
* ``Test.DejaFu.Types.Lookahead``, ``WillSupportsBoundThreads``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
|
||||
* Many functions which had a ``MonadConc`` constraint now have a
|
||||
``MonadDejaFu`` constraint:
|
||||
* In ``Test.DejaFu``
|
||||
* ``autocheck``
|
||||
* ``autocheckWay``
|
||||
* ``autocheckWithSettings``
|
||||
* ``dejafu``
|
||||
* ``dejafuWay``
|
||||
* ``dejafuWithSettings``
|
||||
* ``dejafus``
|
||||
* ``dejafusWay``
|
||||
* ``dejafusWithSettings``
|
||||
* ``runTest``
|
||||
* ``runTestWay``
|
||||
* ``runTestWithSettings``
|
||||
* In ``Test.DejaFu.Conc``
|
||||
* ``runConcurrent``
|
||||
* ``recordSnapshot``
|
||||
* ``runSnapshot``
|
||||
* In ``Test.DejaFu.SCT``
|
||||
* ``runSCT``
|
||||
* ``resultsSet``
|
||||
* ``runSCT'``
|
||||
* ``resultsSet'``
|
||||
* ``runSCTWithSettings``
|
||||
* ``resultsSetWithSettings``
|
||||
* ``runSCTWithSettings'``
|
||||
* ``resultsSetWithSettings'``
|
||||
* Many functions which had a ``MonadConc`` constraint now have a ``MonadDejaFu``
|
||||
constraint:
|
||||
|
||||
* In ``Test.DejaFu``
|
||||
|
||||
* ``autocheck``
|
||||
* ``autocheckWay``
|
||||
* ``autocheckWithSettings``
|
||||
* ``dejafu``
|
||||
* ``dejafuWay``
|
||||
* ``dejafuWithSettings``
|
||||
* ``dejafus``
|
||||
* ``dejafusWay``
|
||||
* ``dejafusWithSettings``
|
||||
* ``runTest``
|
||||
* ``runTestWay``
|
||||
* ``runTestWithSettings``
|
||||
|
||||
* In ``Test.DejaFu.Conc``
|
||||
|
||||
* ``runConcurrent``
|
||||
* ``recordSnapshot``
|
||||
* ``runSnapshot``
|
||||
|
||||
* In ``Test.DejaFu.SCT``
|
||||
|
||||
* ``runSCT``
|
||||
* ``resultsSet``
|
||||
* ``runSCT'``
|
||||
* ``resultsSet'``
|
||||
* ``runSCTWithSettings``
|
||||
* ``resultsSetWithSettings``
|
||||
* ``runSCTWithSettings'``
|
||||
* ``resultsSetWithSettings'``
|
||||
|
||||
Miscellaneous
|
||||
~~~~~~~~~~~~~
|
||||
@ -269,26 +278,29 @@ Added
|
||||
|
||||
* The ``Program`` types and their constructors (re-exported from
|
||||
``Test.DejaFu``):
|
||||
* ``Test.DejaFu.Conc.Program``
|
||||
* ``Test.DejaFu.Conc.Basic``
|
||||
* ``Test.DejaFu.Conc.WithSetup``
|
||||
* ``Test.DejaFu.Conc.WithSetupAndTeardown``
|
||||
* ``Test.DejaFu.Conc.withSetup``
|
||||
* ``Test.DejaFu.Conc.withTeardown``
|
||||
* ``Test.DejaFu.Conc.withSetupAndTeardown``
|
||||
|
||||
* ``Test.DejaFu.Conc.Program``
|
||||
* ``Test.DejaFu.Conc.Basic``
|
||||
* ``Test.DejaFu.Conc.WithSetup``
|
||||
* ``Test.DejaFu.Conc.WithSetupAndTeardown``
|
||||
* ``Test.DejaFu.Conc.withSetup``
|
||||
* ``Test.DejaFu.Conc.withTeardown``
|
||||
* ``Test.DejaFu.Conc.withSetupAndTeardown``
|
||||
|
||||
* The ``Invariant`` type and associated functions (re-exported from
|
||||
``Test.DejaFu``):
|
||||
* ``Test.DejaFu.Conc.Invariant``
|
||||
* ``Test.DejaFu.Conc.registerInvariant``
|
||||
* ``Test.DejaFu.Conc.inspectIORef``
|
||||
* ``Test.DejaFu.Conc.inspectMVar``
|
||||
* ``Test.DejaFu.Conc.inspectTVar``
|
||||
|
||||
* ``Test.DejaFu.Conc.Invariant``
|
||||
* ``Test.DejaFu.Conc.registerInvariant``
|
||||
* ``Test.DejaFu.Conc.inspectIORef``
|
||||
* ``Test.DejaFu.Conc.inspectMVar``
|
||||
* ``Test.DejaFu.Conc.inspectTVar``
|
||||
|
||||
* New snapshotting functions:
|
||||
* ``Test.DejaFu.Conc.Snapshot``
|
||||
* ``Test.DejaFu.Conc.recordSnapshot``
|
||||
* ``Test.DejaFu.Conc.runSnapshot``
|
||||
|
||||
* ``Test.DejaFu.Conc.Snapshot``
|
||||
* ``Test.DejaFu.Conc.recordSnapshot``
|
||||
* ``Test.DejaFu.Conc.runSnapshot``
|
||||
|
||||
* ``Test.DejaFu.Settings.llengthBound``, which now applies to all ways
|
||||
of testing.
|
||||
@ -299,14 +311,15 @@ Added
|
||||
* ``Test.DejaFu.runTestWithSettings`` function.
|
||||
|
||||
* A simplified form of the concurrency state:
|
||||
* ``Test.DejaFu.Types.ConcurrencyState``
|
||||
* ``Test.DejaFu.Types.isBuffered``
|
||||
* ``Test.DejaFu.Types.numBuffered``
|
||||
* ``Test.DejaFu.Types.isFull``
|
||||
* ``Test.DejaFu.Types.canInterrupt``
|
||||
* ``Test.DejaFu.Types.canInterruptL``
|
||||
* ``Test.DejaFu.Types.isMaskedInterruptible``
|
||||
* ``Test.DejaFu.Types.isMaskedUninterruptible``
|
||||
|
||||
* ``Test.DejaFu.Types.ConcurrencyState``
|
||||
* ``Test.DejaFu.Types.isBuffered``
|
||||
* ``Test.DejaFu.Types.numBuffered``
|
||||
* ``Test.DejaFu.Types.isFull``
|
||||
* ``Test.DejaFu.Types.canInterrupt``
|
||||
* ``Test.DejaFu.Types.canInterruptL``
|
||||
* ``Test.DejaFu.Types.isMaskedInterruptible``
|
||||
* ``Test.DejaFu.Types.isMaskedUninterruptible``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
@ -318,75 +331,83 @@ Changed
|
||||
return a representative trace for each unique condition.
|
||||
|
||||
* Functions which took a ``ConcT`` now take a ``Program pty``:
|
||||
* ``Test.DejaFu.autocheck``
|
||||
* ``Test.DejaFu.autocheckWay``
|
||||
* ``Test.DejaFu.autocheckWithSettings``
|
||||
* ``Test.DejaFu.dejafu``
|
||||
* ``Test.DejaFu.dejafuWay``
|
||||
* ``Test.DejaFu.dejafuWithSettings``
|
||||
* ``Test.DejaFu.dejafus``
|
||||
* ``Test.DejaFu.dejafusWay``
|
||||
* ``Test.DejaFu.dejafusWithSettings``
|
||||
* ``Test.DejaFu.runTest``
|
||||
* ``Test.DejaFu.runTestWay``
|
||||
* ``Test.DejaFu.runTestWithSettings``
|
||||
* ``Test.DejaFu.Conc.runConcurrent``
|
||||
* ``Test.DejaFu.SCT.runSCT``
|
||||
* ``Test.DejaFu.SCT.resultsSet``
|
||||
* ``Test.DejaFu.SCT.runSCT'``
|
||||
* ``Test.DejaFu.SCT.resultsSet'``
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings``
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings'``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings'``
|
||||
|
||||
* ``Test.DejaFu.autocheck``
|
||||
* ``Test.DejaFu.autocheckWay``
|
||||
* ``Test.DejaFu.autocheckWithSettings``
|
||||
* ``Test.DejaFu.dejafu``
|
||||
* ``Test.DejaFu.dejafuWay``
|
||||
* ``Test.DejaFu.dejafuWithSettings``
|
||||
* ``Test.DejaFu.dejafus``
|
||||
* ``Test.DejaFu.dejafusWay``
|
||||
* ``Test.DejaFu.dejafusWithSettings``
|
||||
* ``Test.DejaFu.runTest``
|
||||
* ``Test.DejaFu.runTestWay``
|
||||
* ``Test.DejaFu.runTestWithSettings``
|
||||
* ``Test.DejaFu.Conc.runConcurrent``
|
||||
* ``Test.DejaFu.SCT.runSCT``
|
||||
* ``Test.DejaFu.SCT.resultsSet``
|
||||
* ``Test.DejaFu.SCT.runSCT'``
|
||||
* ``Test.DejaFu.SCT.resultsSet'``
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings``
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings'``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings'``
|
||||
|
||||
* ``Test.DejaFu.Conc.ConcT`` is an alias for ``Program Basic``.
|
||||
|
||||
* ``Test.DejaFu.Types.Bounds``:
|
||||
* Removed ``boundLength`` field.
|
||||
|
||||
* Removed ``boundLength`` field.
|
||||
|
||||
* ``Test.DejaFu.Types.Condition``:
|
||||
* Added ``InvariantFailure`` constructor
|
||||
* Removed ``STMDeadlock`` constructor
|
||||
|
||||
* Added ``InvariantFailure`` constructor
|
||||
* Removed ``STMDeadlock`` constructor
|
||||
|
||||
* ``Test.DejaFu.Types.Error``:
|
||||
* Removed ``NestedSubconcurrency``, ``MultithreadedSubconcurrency``,
|
||||
and ``LateDontCheck`` constructors.
|
||||
|
||||
* Removed ``NestedSubconcurrency``, ``MultithreadedSubconcurrency``, and
|
||||
``LateDontCheck`` constructors.
|
||||
|
||||
* ``Test.DejaFu.Types.Lookahead``:
|
||||
* Added ``WillRegisterInvariant`` constructor
|
||||
* Removed ``WillSubconcurrency``, ``WillStopSubconcurrency``, and
|
||||
``WillDontCheck`` constructors
|
||||
|
||||
* Added ``WillRegisterInvariant`` constructor
|
||||
* Removed ``WillSubconcurrency``, ``WillStopSubconcurrency``, and
|
||||
``WillDontCheck`` constructors
|
||||
|
||||
* ``Test.DejaFu.Types.ThreadAction``:
|
||||
* Added ``RegisterInvariant`` constructor
|
||||
* Removed ``Subconcurrency``, ``StopSubconcurrency``, and
|
||||
``DontCheck`` constructors
|
||||
|
||||
* Added ``RegisterInvariant`` constructor
|
||||
* Removed ``Subconcurrency``, ``StopSubconcurrency``, and
|
||||
``DontCheck`` constructors
|
||||
|
||||
Removed
|
||||
~~~~~~~
|
||||
|
||||
* The deprecated functions:
|
||||
* ``Test.DejaFu.dejafuDiscard``
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard``
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard'``
|
||||
* ``Test.DejaFu.SCT.resultsSetDiscard``
|
||||
* ``Test.DejaFu.SCT.resultsSetDiscard'``
|
||||
* ``Test.DejaFu.SCT.sctBound``
|
||||
* ``Test.DejaFu.SCT.sctBoundDiscard``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandom``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandomDiscard``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandom``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandomDiscard``
|
||||
|
||||
* ``Test.DejaFu.dejafuDiscard``
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard``
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard'``
|
||||
* ``Test.DejaFu.SCT.resultsSetDiscard``
|
||||
* ``Test.DejaFu.SCT.resultsSetDiscard'``
|
||||
* ``Test.DejaFu.SCT.sctBound``
|
||||
* ``Test.DejaFu.SCT.sctBoundDiscard``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandom``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandomDiscard``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandom``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandomDiscard``
|
||||
|
||||
* The deprecated type ``Test.DejaFu.Types.Failure``
|
||||
|
||||
* Old snapshotting functions:
|
||||
* ``Test.DejaFu.Conc.DCSnapshot``
|
||||
* ``Test.DejaFu.Conc.runForDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.runWithDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.canDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.threadsFromDCSnapshot``
|
||||
|
||||
* ``Test.DejaFu.Conc.DCSnapshot``
|
||||
* ``Test.DejaFu.Conc.runForDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.runWithDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.canDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.threadsFromDCSnapshot``
|
||||
|
||||
* ``Test.DejaFu.Conc.dontCheck``
|
||||
|
||||
@ -408,8 +429,9 @@ Added
|
||||
|
||||
* ``Test.DejaFu.Types.Error`` for internal errors and misuses, with
|
||||
predicates:
|
||||
* ``Test.DejaFu.Types.isSchedulerError``
|
||||
* ``Test.DejaFu.Types.isIncorrectUsage``
|
||||
|
||||
* ``Test.DejaFu.Types.isSchedulerError``
|
||||
* ``Test.DejaFu.Types.isIncorrectUsage``
|
||||
|
||||
* Deprecated ``Test.DejaFu.Types.Failure`` type synonym for
|
||||
``Condition``.
|
||||
@ -652,9 +674,9 @@ Miscellaneous
|
||||
|
||||
* GHC 7.10 support is dropped. Dependency lower bounds are:
|
||||
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`concurrency`: 1.5
|
||||
* :hackage:`transformers`: 0.5
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`concurrency`: 1.5
|
||||
* :hackage:`transformers`: 0.5
|
||||
|
||||
* The upper bound on :hackage:`concurrency` is 1.6.
|
||||
|
||||
@ -699,8 +721,8 @@ Added
|
||||
|
||||
* (:issue:`183`) SCT settings for trace simplification:
|
||||
|
||||
* ``Test.DejaFu.Settings.lequality``
|
||||
* ``Test.DejaFu.Settings.lsimplify``
|
||||
* ``Test.DejaFu.Settings.lequality``
|
||||
* ``Test.DejaFu.Settings.lsimplify``
|
||||
|
||||
* (:pull:`248`) ``Test.DejaFu.Utils.toTIdTrace`` to extract thread IDs
|
||||
from a trace.
|
||||
@ -726,23 +748,23 @@ Added
|
||||
|
||||
* (:pull:`246`) ``Generic`` instances for:
|
||||
|
||||
* ``Test.DejaFu.Types.ThreadId``
|
||||
* ``Test.DejaFu.Types.CRefId``
|
||||
* ``Test.DejaFu.Types.MVarId``
|
||||
* ``Test.DejaFu.Types.TVarId``
|
||||
* ``Test.DejaFu.Types.Id``
|
||||
* ``Test.DejaFu.Types.ThreadAction``
|
||||
* ``Test.DejaFu.Types.Lookahead``
|
||||
* ``Test.DejaFu.Types.TAction``
|
||||
* ``Test.DejaFu.Types.Decision``
|
||||
* ``Test.DejaFu.Types.Failure``
|
||||
* ``Test.DejaFu.Types.Bounds``
|
||||
* ``Test.DejaFu.Types.PreemptionBound``
|
||||
* ``Test.DejaFu.Types.FairBound``
|
||||
* ``Test.DejaFu.Types.LengthBound``
|
||||
* ``Test.DejaFu.Types.Discard``
|
||||
* ``Test.DejaFu.Types.MemType``
|
||||
* ``Test.DejaFu.Types.MonadFailException``
|
||||
* ``Test.DejaFu.Types.ThreadId``
|
||||
* ``Test.DejaFu.Types.CRefId``
|
||||
* ``Test.DejaFu.Types.MVarId``
|
||||
* ``Test.DejaFu.Types.TVarId``
|
||||
* ``Test.DejaFu.Types.Id``
|
||||
* ``Test.DejaFu.Types.ThreadAction``
|
||||
* ``Test.DejaFu.Types.Lookahead``
|
||||
* ``Test.DejaFu.Types.TAction``
|
||||
* ``Test.DejaFu.Types.Decision``
|
||||
* ``Test.DejaFu.Types.Failure``
|
||||
* ``Test.DejaFu.Types.Bounds``
|
||||
* ``Test.DejaFu.Types.PreemptionBound``
|
||||
* ``Test.DejaFu.Types.FairBound``
|
||||
* ``Test.DejaFu.Types.LengthBound``
|
||||
* ``Test.DejaFu.Types.Discard``
|
||||
* ``Test.DejaFu.Types.MemType``
|
||||
* ``Test.DejaFu.Types.MonadFailException``
|
||||
|
||||
* (:pull:`246`) ``NFData`` instance for
|
||||
``Test.DejaFu.Types.MonadFailException``
|
||||
@ -817,49 +839,55 @@ Added
|
||||
|
||||
* (:pull:`238`) A record-based approach to SCT configuration:
|
||||
|
||||
* ``Test.DejaFu.Settings``
|
||||
(re-exported from ``Test.Dejafu`` and ``Test.DejaFu.SCT``)
|
||||
* ``Test.DejaFu.Settings.Settings``
|
||||
* ``Test.DejaFu.Settings.defaultSettings``
|
||||
* ``Test.DejaFu.Settings.fromWayAndMemType``
|
||||
* Lenses:
|
||||
* ``Test.DejaFu.Settings.lway``
|
||||
* ``Test.DejaFu.Settings.lmemtype``
|
||||
* ``Test.DejaFu.Settings.ldiscard``
|
||||
* ``Test.DejaFu.Settings.learlyExit``
|
||||
* ``Test.DejaFu.Settings.ldebugShow``
|
||||
* ``Test.DejaFu.Settings.ldebugPrint``
|
||||
* Lens helpers:
|
||||
* ``Test.DejaFu.Settings.get``
|
||||
* ``Test.DejaFu.Settings.set``
|
||||
* Runners:
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings``
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings'``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings'``
|
||||
* ``Test.DejaFu.Settings`` (re-exported from ``Test.Dejafu`` and
|
||||
``Test.DejaFu.SCT``)
|
||||
* ``Test.DejaFu.Settings.Settings``
|
||||
* ``Test.DejaFu.Settings.defaultSettings``
|
||||
* ``Test.DejaFu.Settings.fromWayAndMemType``
|
||||
|
||||
* Lenses:
|
||||
|
||||
* ``Test.DejaFu.Settings.lway``
|
||||
* ``Test.DejaFu.Settings.lmemtype``
|
||||
* ``Test.DejaFu.Settings.ldiscard``
|
||||
* ``Test.DejaFu.Settings.learlyExit``
|
||||
* ``Test.DejaFu.Settings.ldebugShow``
|
||||
* ``Test.DejaFu.Settings.ldebugPrint``
|
||||
|
||||
* Lens helpers:
|
||||
|
||||
* ``Test.DejaFu.Settings.get``
|
||||
* ``Test.DejaFu.Settings.set``
|
||||
|
||||
* Runners:
|
||||
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings``
|
||||
* ``Test.DejaFu.SCT.runSCTWithSettings'``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings``
|
||||
* ``Test.DejaFu.SCT.resultsSetWithSettings'``
|
||||
|
||||
* (:pull:`238`) Settings-based test functions:
|
||||
|
||||
* ``Test.DejaFu.autocheckWithSettings``
|
||||
* ``Test.DejaFu.dejafuWithSettings``
|
||||
* ``Test.DejaFu.dejafusWithSettings``
|
||||
* ``Test.DejaFu.runTestWithSettings``
|
||||
* ``Test.DejaFu.autocheckWithSettings``
|
||||
* ``Test.DejaFu.dejafuWithSettings``
|
||||
* ``Test.DejaFu.dejafusWithSettings``
|
||||
* ``Test.DejaFu.runTestWithSettings``
|
||||
|
||||
Deprecated
|
||||
~~~~~~~~~~
|
||||
|
||||
* (:pull:`238`) SCT function variants:
|
||||
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard``
|
||||
* ``Test.DejaFu.SCT.resultSetDiscard``
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard'``
|
||||
* ``Test.DejaFu.SCT.resultSetDiscard'``
|
||||
* ``Test.DejaFu.SCT.sctBound``
|
||||
* ``Test.DejaFu.SCT.sctBoundDiscard``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandom``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandomDiscard``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandom``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandomDiscard``
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard``
|
||||
* ``Test.DejaFu.SCT.resultSetDiscard``
|
||||
* ``Test.DejaFu.SCT.runSCTDiscard'``
|
||||
* ``Test.DejaFu.SCT.resultSetDiscard'``
|
||||
* ``Test.DejaFu.SCT.sctBound``
|
||||
* ``Test.DejaFu.SCT.sctBoundDiscard``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandom``
|
||||
* ``Test.DejaFu.SCT.sctUniformRandomDiscard``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandom``
|
||||
* ``Test.DejaFu.SCT.sctWeightedRandomDiscard``
|
||||
|
||||
* (:pull:`238`) The ``Test.DejaFu.Defaults`` module. Import
|
||||
``Test.DejaFu.Settings`` instead.
|
||||
@ -915,18 +943,18 @@ Added
|
||||
* (:pull:`219`) The testing-only ``Test.DejaFu.Conc.dontCheck``
|
||||
function, and associated definitions:
|
||||
|
||||
* ``Test.DejaFu.Types.DontCheck``
|
||||
* ``Test.DejaFu.Types.WillDontCheck``
|
||||
* ``Test.DejaFu.Types.IllegalDontCheck``
|
||||
* ``Test.DejaFu.Types.isIllegalDontCheck``
|
||||
* ``Test.DejaFu.Types.DontCheck``
|
||||
* ``Test.DejaFu.Types.WillDontCheck``
|
||||
* ``Test.DejaFu.Types.IllegalDontCheck``
|
||||
* ``Test.DejaFu.Types.isIllegalDontCheck``
|
||||
|
||||
* (:pull:`219`) A snapshotting approach based on
|
||||
``Test.DejaFu.Conc.dontCheck``:
|
||||
|
||||
* ``Test.DejaFu.Conc.runForDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.runWithDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.canDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.threadsFromDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.runForDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.runWithDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.canDCSnapshot``
|
||||
* ``Test.DejaFu.Conc.threadsFromDCSnapshot``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
@ -1011,10 +1039,10 @@ Added
|
||||
|
||||
* (:pull:`145`) Thread action and lookahead values for bound threads:
|
||||
|
||||
* ``Test.DejaFu.Types.ForkOS``
|
||||
* ``Test.DejaFu.Types.IsCurrentThreadBound``
|
||||
* ``Test.DejaFu.Types.WillForkOS``
|
||||
* ``Test.DejaFu.Types.WillIsCurrentThreadBound``
|
||||
* ``Test.DejaFu.Types.ForkOS``
|
||||
* ``Test.DejaFu.Types.IsCurrentThreadBound``
|
||||
* ``Test.DejaFu.Types.WillForkOS``
|
||||
* ``Test.DejaFu.Types.WillIsCurrentThreadBound``
|
||||
|
||||
* (:issue:`155`) ``Test.DejaFu.Types`` and ``Test.DejaFu.Utils``
|
||||
modules, each containing some of what was in ``Test.DejaFu.Common``.
|
||||
@ -1064,15 +1092,15 @@ Removed
|
||||
|
||||
* The ``IO`` specific testing functions:
|
||||
|
||||
* ``Test.DejaFu.autocheckIO``
|
||||
* ``Test.DejaFu.dejafuIO``
|
||||
* ``Test.DejaFu.dejafusIO``
|
||||
* ``Test.DejaFu.autocheckWayIO``
|
||||
* ``Test.DejaFu.dejafuWayIO``
|
||||
* ``Test.DejaFu.dejafusWayIO``
|
||||
* ``Test.DejaFu.dejafuDiscardIO``
|
||||
* ``Test.DejaFu.runTestM``
|
||||
* ``Test.DejaFu.runTestWayM``
|
||||
* ``Test.DejaFu.autocheckIO``
|
||||
* ``Test.DejaFu.dejafuIO``
|
||||
* ``Test.DejaFu.dejafusIO``
|
||||
* ``Test.DejaFu.autocheckWayIO``
|
||||
* ``Test.DejaFu.dejafuWayIO``
|
||||
* ``Test.DejaFu.dejafusWayIO``
|
||||
* ``Test.DejaFu.dejafuDiscardIO``
|
||||
* ``Test.DejaFu.runTestM``
|
||||
* ``Test.DejaFu.runTestWayM``
|
||||
|
||||
* The ``Test.DejaFu.Conc.ConcST`` type alias.
|
||||
|
||||
@ -1214,16 +1242,16 @@ Added
|
||||
|
||||
* Failure predicates (also exported from ``Test.DejaFu``):
|
||||
|
||||
* ``Test.DejaFu.Common.isAbort``
|
||||
* ``Test.DejaFu.Common.isDeadlock``
|
||||
* ``Test.DejaFu.Common.isIllegalSubconcurrency``
|
||||
* ``Test.DejaFu.Common.isInternalError``
|
||||
* ``Test.DejaFu.Common.isUncaughtException``
|
||||
* ``Test.DejaFu.Common.isAbort``
|
||||
* ``Test.DejaFu.Common.isDeadlock``
|
||||
* ``Test.DejaFu.Common.isIllegalSubconcurrency``
|
||||
* ``Test.DejaFu.Common.isInternalError``
|
||||
* ``Test.DejaFu.Common.isUncaughtException``
|
||||
|
||||
* Thread action and lookahead values for ``threadDelay``:
|
||||
|
||||
* ``Test.DejaFu.Common.ThreadDelay``
|
||||
* ``Test.DejaFu.Common.WillThreadDelay``
|
||||
* ``Test.DejaFu.Common.ThreadDelay``
|
||||
* ``Test.DejaFu.Common.WillThreadDelay``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
@ -1350,8 +1378,8 @@ Performance
|
||||
* (:issue:`64`) Greatly reduce memory usage in systematic testing when
|
||||
discarding traces by using an alternative data structure.
|
||||
|
||||
* Old: ``O(max trace length * number of executions)``
|
||||
* New: ``O(max trace length * number of traces kept)``
|
||||
* Old: ``O(max trace length * number of executions)``
|
||||
* New: ``O(max trace length * number of traces kept)``
|
||||
|
||||
|
||||
0.7.1.0 - The Discard Release (2017-08-10)
|
||||
@ -1365,15 +1393,15 @@ Added
|
||||
|
||||
* (:issue:`90`) A way to selectively discard results or traces:
|
||||
|
||||
* Type: ``Test.DejaFu.SCT.Discard``
|
||||
* Functions: ``Test.DejaFu.SCT.runSCTDiscard``,
|
||||
``resultsSetDiscard``, ``sctBoundDiscard``,
|
||||
``sctUniformRandomDiscard``, and ``sctWeightedRandomDiscard``.
|
||||
* Type: ``Test.DejaFu.SCT.Discard``
|
||||
* Functions: ``Test.DejaFu.SCT.runSCTDiscard``, ``resultsSetDiscard``,
|
||||
``sctBoundDiscard``, ``sctUniformRandomDiscard``, and
|
||||
``sctWeightedRandomDiscard``.
|
||||
|
||||
* (:issue:`90`) Discarding variants of the testing functions:
|
||||
|
||||
* ``Test.DejaFu.dejafuDiscard``
|
||||
* ``Test.DejaFu.dejafuDiscardIO``
|
||||
* ``Test.DejaFu.dejafuDiscard``
|
||||
* ``Test.DejaFu.dejafuDiscardIO``
|
||||
|
||||
* (:issue:`90`) ``Test.DejaFu.Defaults.defaultDiscarder``.
|
||||
|
||||
@ -1439,13 +1467,12 @@ Added
|
||||
* Smart constructors for ``Test.DejaFu.SCT.Way`` (also re-exported
|
||||
from ``Test.DejaFu``):
|
||||
|
||||
* ``Test.DejaFu.SCT.systematically``, like the old
|
||||
``Systematically``.
|
||||
* ``Test.DejaFu.SCT.randomly``, like the old ``Randomly``.
|
||||
* ``Test.DejaFu.SCT.uniformly``, a new uniform (as opposed to
|
||||
weighted) random scheduler.
|
||||
* ``Test.DejaFu.SCT.swarmy``, like the old ``Randomly`` but which
|
||||
can use the same weights for multiple executions.
|
||||
* ``Test.DejaFu.SCT.systematically``, like the old ``Systematically``.
|
||||
* ``Test.DejaFu.SCT.randomly``, like the old ``Randomly``.
|
||||
* ``Test.DejaFu.SCT.uniformly``, a new uniform (as opposed to weighted) random
|
||||
scheduler.
|
||||
* ``Test.DejaFu.SCT.swarmy``, like the old ``Randomly`` but which can use the
|
||||
same weights for multiple executions.
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
@ -1463,8 +1490,8 @@ Removed
|
||||
* The ``Test.DejaFu.SCT.Way`` type is now abstract, so its
|
||||
constructors are no longer exported:
|
||||
|
||||
* ``Test.DejaFu.SCT.Systematically``
|
||||
* ``Test.DejaFu.SCT.Randomly``
|
||||
* ``Test.DejaFu.SCT.Systematically``
|
||||
* ``Test.DejaFu.SCT.Randomly``
|
||||
|
||||
* The ``Test.DejaFu.SCT.sctPreBound``, ``sctFairBound``, and
|
||||
``sctLengthBound`` functions.
|
||||
@ -1571,25 +1598,25 @@ Added
|
||||
|
||||
* ``NFData`` instances for:
|
||||
|
||||
* ``Test.DejaFu.Result``
|
||||
* ``Test.DejaFu.Common.ThreadId``
|
||||
* ``Test.DejaFu.Common.CRefId``
|
||||
* ``Test.DejaFu.Common.MVarId``
|
||||
* ``Test.DejaFu.Common.TVarId``
|
||||
* ``Test.DejaFu.Common.IdSource``
|
||||
* ``Test.DejaFu.Common.ThreadAction``
|
||||
* ``Test.DejaFu.Common.Lookahead``
|
||||
* ``Test.DejaFu.Common.ActionType``
|
||||
* ``Test.DejaFu.Common.TAction``
|
||||
* ``Test.DejaFu.Common.Decision``
|
||||
* ``Test.DejaFu.Common.Failure``
|
||||
* ``Test.DejaFu.Common.MemType``
|
||||
* ``Test.DejaFu.SCT.Bounds``
|
||||
* ``Test.DejaFu.SCT.PreemptionBound``
|
||||
* ``Test.DejaFu.SCT.FairBound``
|
||||
* ``Test.DejaFu.SCT.LengthBound``
|
||||
* ``Test.DejaFu.SCT.Way``
|
||||
* ``Test.DejaFu.STM.Result``
|
||||
* ``Test.DejaFu.Result``
|
||||
* ``Test.DejaFu.Common.ThreadId``
|
||||
* ``Test.DejaFu.Common.CRefId``
|
||||
* ``Test.DejaFu.Common.MVarId``
|
||||
* ``Test.DejaFu.Common.TVarId``
|
||||
* ``Test.DejaFu.Common.IdSource``
|
||||
* ``Test.DejaFu.Common.ThreadAction``
|
||||
* ``Test.DejaFu.Common.Lookahead``
|
||||
* ``Test.DejaFu.Common.ActionType``
|
||||
* ``Test.DejaFu.Common.TAction``
|
||||
* ``Test.DejaFu.Common.Decision``
|
||||
* ``Test.DejaFu.Common.Failure``
|
||||
* ``Test.DejaFu.Common.MemType``
|
||||
* ``Test.DejaFu.SCT.Bounds``
|
||||
* ``Test.DejaFu.SCT.PreemptionBound``
|
||||
* ``Test.DejaFu.SCT.FairBound``
|
||||
* ``Test.DejaFu.SCT.LengthBound``
|
||||
* ``Test.DejaFu.SCT.Way``
|
||||
* ``Test.DejaFu.STM.Result``
|
||||
|
||||
* ``Eq``, ``Ord``, and ``Show`` instances for
|
||||
``Test.DejaFu.Common.IdSource``.
|
||||
@ -1661,8 +1688,8 @@ Added
|
||||
|
||||
* Thread action and lookahead values for ``tryReadMVar``:
|
||||
|
||||
* ``Test.DejaFu.Common.TryReadMVar``
|
||||
* ``Test.DejaFu.Common.WillTryReadMVar``
|
||||
* ``Test.DejaFu.Common.TryReadMVar``
|
||||
* ``Test.DejaFu.Common.WillTryReadMVar``
|
||||
|
||||
* The testing-only ``Test.DejaFu.Conc.subconcurrency`` function.
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ dejafu
|
||||
- [Release notes](#release-notes)
|
||||
- [Questions, feedback, discussion](#questions-feedback-discussion)
|
||||
- [Bibliography](#bibliography)
|
||||
- **[The website!](http://dejafu.readthedocs.io/)**
|
||||
- **[The website!](https://dejafu.docs.barrucadu.co.uk/)**
|
||||
|
||||
Déjà Fu is a unit-testing library for concurrent Haskell programs.
|
||||
Tests are deterministic and expressive, making it easy and convenient
|
||||
|
||||
@ -13,7 +13,7 @@ are written using the <https://hackage.haskell.org/package/concurrency
|
||||
concurrency> package's 'MonadConc' typeclass.
|
||||
|
||||
For more in-depth documentation, including migration guides from
|
||||
earlier versions of dejafu, see the <https://dejafu.readthedocs.io
|
||||
earlier versions of dejafu, see the <https://dejafu.docs.barrucadu.co.uk/
|
||||
website>.
|
||||
|
||||
__A first test:__ This is a simple concurrent program which forks two
|
||||
|
||||
@ -13,7 +13,7 @@ description:
|
||||
package by enabling you to deterministically test your concurrent
|
||||
programs.
|
||||
.
|
||||
See the <https://dejafu.readthedocs.io website> or README for more.
|
||||
See the <https://dejafu.docs.barrucadu.co.uk/ website> or README for more.
|
||||
|
||||
homepage: https://github.com/barrucadu/dejafu
|
||||
license: MIT
|
||||
|
||||
1
doc/.gitignore
vendored
1
doc/.gitignore
vendored
@ -1 +0,0 @@
|
||||
_build
|
||||
102
doc/advanced.rst
102
doc/advanced.rst
@ -1,102 +0,0 @@
|
||||
Advanced Usage
|
||||
==============
|
||||
|
||||
Déjà Fu tries to have a sensible set of defaults, but there are some
|
||||
times when the defaults are not suitable. There are a lot of knobs
|
||||
provided to tweak how things work.
|
||||
|
||||
|
||||
.. _settings:
|
||||
|
||||
Execution settings
|
||||
------------------
|
||||
|
||||
The ``autocheckWithSettings``, ``dejafuWithSettings``, and
|
||||
``dejafusWithSettings`` let you provide a ``Settings`` value, which
|
||||
controls some of Déjà Fu's behaviour:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
dejafuWithSettings mySettings "Assert the thing holds" myPredicate myAction
|
||||
|
||||
The available settings are:
|
||||
|
||||
* **"Way"**, how to explore the behaviours of the program under test.
|
||||
|
||||
* **Length bound**, a cut-off point to terminate an execution even if
|
||||
it's not done yet.
|
||||
|
||||
* **Memory model**, which affects how non-synchronised operations,
|
||||
such as ``readIORef`` and ``writeIORef`` behave.
|
||||
|
||||
* **Discarding**, which allows throwing away uninteresting results,
|
||||
rather than keeping them around in memory.
|
||||
|
||||
* **Early exit**, which allows exiting as soon as a result matching a
|
||||
predicate is found.
|
||||
|
||||
* **Representative traces**, keeping only one execution trace for each
|
||||
distinct result.
|
||||
|
||||
* **Trace simplification**, rewriting execution traces into a simpler
|
||||
form (particularly effective with the random testing).
|
||||
|
||||
* **Safe IO**, pruning needless schedules when your IO is only used to
|
||||
manage thread-local state.
|
||||
|
||||
See the ``Test.DejaFu.Settings`` module for more information.
|
||||
|
||||
|
||||
.. _performance:
|
||||
|
||||
Performance tuning
|
||||
------------------
|
||||
|
||||
* Are you happy to trade space for time?
|
||||
|
||||
Consider computing the results once and running multiple
|
||||
predicates over the output: this is what ``dejafus`` /
|
||||
``testDejafus`` / etc does.
|
||||
|
||||
* Can you sacrifice completeness?
|
||||
|
||||
Consider using the random testing functionality. See the ``*WithSettings``
|
||||
functions.
|
||||
|
||||
* Would strictness help?
|
||||
|
||||
Consider using the strict functions in ``Test.DejaFu.SCT`` (the
|
||||
ones ending with a ``'``).
|
||||
|
||||
* Do you just want the set of results, and don't care about traces?
|
||||
|
||||
Consider using ``Test.DejaFu.SCT.resultsSet``.
|
||||
|
||||
* Do you know something about the sort of results you care about?
|
||||
|
||||
Consider discarding results you *don't* care about. See the
|
||||
``*WithSettings`` functions in ``Test.DejaFu``, ``Test.DejaFu.SCT``,
|
||||
and ``Test.{HUnit,Tasty}.DejaFu``.
|
||||
|
||||
For example, let's say you want to know if your test case deadlocks,
|
||||
but you don't care about the execution trace, and you are going to
|
||||
sacrifice completeness because your possible state-space is huge. You
|
||||
could do it like this:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
dejafuWithSettings
|
||||
( set ldiscard
|
||||
-- "efa" == "either failure a", discard everything but deadlocks
|
||||
(Just $ \efa -> Just (if either isDeadlock (const False) efa then DiscardTrace else DiscardResultAndTrace))
|
||||
. set lway
|
||||
-- try 10000 executions with random scheduling
|
||||
(randomly (mkStdGen 42) 10000)
|
||||
$ defaultSettings
|
||||
)
|
||||
-- the name of the test
|
||||
"Never Deadlocks"
|
||||
-- the predicate to check
|
||||
deadlocksNever
|
||||
-- your test case
|
||||
testCase
|
||||
@ -1 +0,0 @@
|
||||
../concurrency/CHANGELOG.rst
|
||||
@ -1 +0,0 @@
|
||||
../dejafu/CHANGELOG.rst
|
||||
@ -1 +0,0 @@
|
||||
../hunit-dejafu/CHANGELOG.rst
|
||||
@ -1 +0,0 @@
|
||||
../tasty-dejafu/CHANGELOG.rst
|
||||
171
doc/conf.py
171
doc/conf.py
@ -1,171 +0,0 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# Déjà Fu documentation build configuration file, created by
|
||||
# sphinx-quickstart on Tue Aug 15 19:55:19 2017.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
import os
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['sphinx.ext.extlinks']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
source_parsers = {
|
||||
}
|
||||
|
||||
source_suffix = ['.rst']
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'Déjà Fu'
|
||||
copyright = u'2017--2018, Michael Walker'
|
||||
author = u'Michael Walker'
|
||||
|
||||
# External link destinations
|
||||
_repo = 'https://github.com/barrucadu/dejafu/'
|
||||
extlinks = {
|
||||
'commit': (_repo + 'commit/%s', 'commit '),
|
||||
'issue': (_repo + 'issues/%s', 'issue #'),
|
||||
'pull': (_repo + 'pull/%s', 'pull request #'),
|
||||
'tag': (_repo + 'releases/tag/%s', 'tag '),
|
||||
'github': (_repo + '%s', ''),
|
||||
'u': ('https://github.com/%s', ''),
|
||||
'hackage': ('https://hackage.haskell.org/package/%s', ''),
|
||||
'stackage': ('https://www.stackage.org/package/%s', ''),
|
||||
}
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = u'HEAD'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = u'HEAD'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This patterns also effect to html_static_path and html_extra_path
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = os.environ['SPHINX_THEME'] if 'SPHINX_THEME' in os.environ else 'default'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
# html_theme_options = {}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'DejaFudoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'DejaFu.tex', u'Déjà Fu Documentation',
|
||||
u'Michael Walker', 'manual'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'dejafu', u'Déjà Fu Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'DejaFu', u'Déjà Fu Documentation',
|
||||
author, 'DejaFu', 'Concurrency testing for Haskell.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
|
||||
@ -1,219 +0,0 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
Thanks for caring about Déjà Fu!
|
||||
|
||||
|
||||
Ways to contribute
|
||||
------------------
|
||||
|
||||
Déjà Fu is a project under active development, there's always
|
||||
something to do. Here's a list of ideas to get you started:
|
||||
|
||||
* Submit bug reports.
|
||||
* Submit feature requests.
|
||||
* Got a particularly slow test case which you think should be faster?
|
||||
Open an issue for that too.
|
||||
* Blog about how and why you use Déjà Fu.
|
||||
* Check if any bugs which have been open for a while are still bugs.
|
||||
|
||||
If you want to contribute code, you could:
|
||||
|
||||
* Tackle one of the issues tagged :github:`"good first issue" <labels/good%20first%20issue>`.
|
||||
* Tackle a bigger issue, perhaps one of the :github:`roadmap issues <labels/roadmap>`!
|
||||
* Run code coverage and try to fix a gap in the tests.
|
||||
* Profile the test suite and try to improve a slow function.
|
||||
|
||||
:github:`Roadmap issues <labels/roadmap>` are priority issues (in my
|
||||
opinion), so help with those is especially appreciated.
|
||||
|
||||
If you have a support question, you can talk to me on IRC (#haskell on
|
||||
freenode) or send an email (mike@barrucadu.co.uk) rather than opening
|
||||
an issue. But maybe your question is a bug report about poor
|
||||
documentation in disguise!
|
||||
|
||||
|
||||
Making the change
|
||||
-----------------
|
||||
|
||||
1. Talk to me!
|
||||
|
||||
I don't bite, and chances are I can quickly tell you where you
|
||||
should start. It's better to ask what seems like a stupid question
|
||||
than to waste a lot of time on the wrong approach.
|
||||
|
||||
2. Make the change.
|
||||
|
||||
Figure out what needs to be changed, how to change it, and do it.
|
||||
If you're fixing a bug, make sure to add a minimal reproduction to
|
||||
Cases.Regressions in dejafu-tests.
|
||||
|
||||
3. Document the change.
|
||||
|
||||
All top-level definitions should have a `Haddock`__ comment
|
||||
explaining what it does. If you've added or changed a top-level
|
||||
function, consider commenting its arguments too.
|
||||
|
||||
If you've added a top-level definition, or changed one in a
|
||||
backwards-incompatible way, add an ``@since unreleased`` Haddock
|
||||
comment to it. This is to help prevent me from missing things when
|
||||
I update the changelog ahead of a release.
|
||||
|
||||
4. Submit a PR.
|
||||
|
||||
GitHub Actions will run some checks, which might prompt further
|
||||
action. You should expect a response from me in a day or two.
|
||||
|
||||
Don't worry about your PR being perfect the first time. We'll work
|
||||
through any issues together, to ensure that Déjà Fu gets the best code
|
||||
it can.
|
||||
|
||||
.. __: https://github.com/aisamanra/haddock-cheatsheet
|
||||
|
||||
|
||||
Coding style
|
||||
------------
|
||||
|
||||
There isn't really a prescribed style. It's not quite the wild west
|
||||
though; keep these three rules in mind:
|
||||
|
||||
1. Be consistent.
|
||||
2. Run :hackage:`stylish-haskell` to format import lists.
|
||||
3. Use :hackage:`hlint` and :hackage:`weeder` and fix lints unless you
|
||||
have a good reason not to.
|
||||
|
||||
GitHub Actions runs stylish-haskell and hlint on all PRs.
|
||||
|
||||
|
||||
Coverage
|
||||
--------
|
||||
|
||||
`hpc`__ can generate a coverage report from the execution of
|
||||
dejafu-tests:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ stack build --coverage
|
||||
$ stack exec dejafu-tests
|
||||
$ stack hpc report --all dejafu-tests.tix
|
||||
|
||||
This will print some stats and generate an HTML coverage report:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Generating combined report
|
||||
52% expressions used (4052/7693)
|
||||
48% boolean coverage (63/129)
|
||||
43% guards (46/106), 31 always True, 9 always False, 20 unevaluated
|
||||
68% 'if' conditions (11/16), 2 always True, 3 unevaluated
|
||||
85% qualifiers (6/7), 1 unevaluated
|
||||
61% alternatives used (392/635)
|
||||
80% local declarations used (210/261)
|
||||
26% top-level declarations used (280/1063)
|
||||
The combined report is available at /home/barrucadu/projects/dejafu/.stack-work/install/x86_64-linux/nightly-2016-06-20/8.0.1/hpc/combined/custom/hpc_index.html
|
||||
|
||||
The highlighted code in the HTML report emphasises branch coverage:
|
||||
|
||||
* Red means a branch was evaluated as always false.
|
||||
* Green means a branch was evaluated as always true.
|
||||
* Yellow means an expression was never evaluated.
|
||||
|
||||
See also the `stack coverage documentation`__.
|
||||
|
||||
.. __: https://wiki.haskell.org/Haskell_program_coverage
|
||||
.. __: https://docs.haskellstack.org/en/latest/coverage/
|
||||
|
||||
|
||||
Performance
|
||||
-----------
|
||||
|
||||
GHC can generate performance statistics from the execution of
|
||||
dejafu-tests:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ stack build --profile
|
||||
$ stack exec -- dejafu-tests +RTS -p
|
||||
$ less dejafu-tests.prof
|
||||
|
||||
This prints a detailed breakdown of where memory and time are being
|
||||
spent:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Mon Mar 20 19:26 2017 Time and Allocation Profiling Report (Final)
|
||||
|
||||
dejafu-tests +RTS -p -RTS
|
||||
|
||||
total time = 105.94 secs (105938 ticks @ 1000 us, 1 processor)
|
||||
total alloc = 46,641,766,952 bytes (excludes profiling overheads)
|
||||
|
||||
COST CENTRE MODULE %time %alloc
|
||||
|
||||
findBacktrackSteps.doBacktrack.idxs' Test.DejaFu.SCT.Internal 21.9 12.0
|
||||
== Test.DejaFu.Common 12.4 0.0
|
||||
yieldCount.go Test.DejaFu.SCT 12.1 0.0
|
||||
dependent' Test.DejaFu.SCT 5.1 0.0
|
||||
runThreads.go Test.DejaFu.Conc.Internal 2.7 4.1
|
||||
[...]
|
||||
|
||||
Be careful, however! Compiling with profiling can significantly
|
||||
affect the behaviour of a program! Use profiling to get an idea of
|
||||
where the hot spots are, but make sure to confirm with a non-profiled
|
||||
build that things are actually getting faster.
|
||||
|
||||
If you compile with ``-rtsopts`` you can get some basic stats from a
|
||||
non-profiled build:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ stack exec -- dejafu-tests +RTS -s
|
||||
|
||||
[...]
|
||||
86,659,658,504 bytes allocated in the heap
|
||||
13,057,037,448 bytes copied during GC
|
||||
13,346,952 bytes maximum residency (4743 sample(s))
|
||||
127,824 bytes maximum slop
|
||||
37 MB total memory in use (0 MB lost due to fragmentation)
|
||||
|
||||
Tot time (elapsed) Avg pause Max pause
|
||||
Gen 0 78860 colls, 0 par 32.659s 32.970s 0.0004s 0.0669s
|
||||
Gen 1 4743 colls, 0 par 3.043s 3.052s 0.0006s 0.0086s
|
||||
|
||||
TASKS: 174069 (174065 bound, 4 peak workers (4 total), using -N1)
|
||||
|
||||
SPARKS: 0 (0 converted, 0 overflowed, 0 dud, 0 GC'd, 0 fizzled)
|
||||
|
||||
INIT time 0.001s ( 0.001s elapsed)
|
||||
MUT time 98.685s (101.611s elapsed)
|
||||
GC time 35.702s ( 36.022s elapsed)
|
||||
EXIT time 0.001s ( 0.007s elapsed)
|
||||
Total time 134.388s (137.640s elapsed)
|
||||
|
||||
Alloc rate 878,145,635 bytes per MUT second
|
||||
|
||||
Productivity 73.4% of total user, 73.8% of total elapsed
|
||||
|
||||
|
||||
Heap profiling
|
||||
--------------
|
||||
|
||||
GHC can tell you where the memory is going:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ stack build --profile
|
||||
$ stack exec -- dejafu-tests +RTS -hc
|
||||
$ hp2ps -c dejafu-tests.hp
|
||||
|
||||
This will produce a graph of memory usage over time, as a postscript
|
||||
file, broken down by cost-centre which produced the data. There are a
|
||||
few different views:
|
||||
|
||||
- ``-hm`` breaks down the graph by module
|
||||
- ``-hd`` breaks down the graph by closure description
|
||||
- ``-hy`` breaks down the graph by type
|
||||
|
||||
I typically find ``-hd`` and ``-hy`` most useful. If you're feeling
|
||||
particularly brave, you can try ``-hr``, which is intended to help
|
||||
track down memory leaks caused by unevaluated thunks.
|
||||
@ -1,161 +0,0 @@
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
[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**
|
||||
|
||||
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:`GitHub <>`,
|
||||
:hackage:`Hackage <dejafu>`, and :stackage:`Stackage <dejafu>`.
|
||||
|
||||
Features:
|
||||
|
||||
* 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 :hackage:`HUnit` and :hackage:`tasty`
|
||||
|
||||
There are a few different packages under the Déjà Fu umbrella:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Package", "Version", "Summary"
|
||||
|
||||
":hackage:`concurrency`", "1.11.0.3", "Typeclasses, functions, and data types for concurrency and STM"
|
||||
":hackage:`dejafu`", "2.4.0.5", "Systematic testing for Haskell concurrency"
|
||||
":hackage:`hunit-dejafu`", "2.0.0.6", "Déjà Fu support for the HUnit test framework"
|
||||
":hackage:`tasty-dejafu`", "2.1.0.1", "Déjà Fu support for the tasty test framework"
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
Install from Hackage globally:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cabal install dejafu
|
||||
|
||||
Or add it to your cabal file:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
build-depends: ...
|
||||
, dejafu
|
||||
|
||||
Or to your package.yaml:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
dependencies:
|
||||
...
|
||||
- dejafu
|
||||
|
||||
|
||||
Quick start guide
|
||||
-----------------
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
import Control.Concurrent.Classy
|
||||
|
||||
myFunction :: MonadConc m => m String
|
||||
myFunction = do
|
||||
var <- newEmptyMVar
|
||||
fork (putMVar var "hello")
|
||||
fork (putMVar var "world")
|
||||
readMVar var
|
||||
|
||||
That ``MonadConc`` is a typeclass abstraction over concurrency, but
|
||||
we'll get onto that shortly. First, the result of testing:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
> autocheck myFunction
|
||||
[pass] Successful
|
||||
[fail] Deterministic
|
||||
"hello" S0----S1--S0--
|
||||
|
||||
"world" S0----S2--S0--
|
||||
False
|
||||
|
||||
There are no concurrency errors, which is good; but the program is (as
|
||||
you probably spotted) nondeterministic!
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Why Déjà Fu?
|
||||
------------
|
||||
|
||||
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 scheduling variety than just
|
||||
running your test case in ``IO`` a bunch 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 following the trace by
|
||||
eye.
|
||||
|
||||
**If you'd like to get involved with Déjà Fu**, check out :github:`the
|
||||
"good first issue" label on the issue tracker
|
||||
<issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22>`.
|
||||
|
||||
|
||||
Questions, feedback, discussion
|
||||
-------------------------------
|
||||
|
||||
* 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 :issue:`file an issue <>`.
|
||||
|
||||
|
||||
Bibliography
|
||||
------------
|
||||
|
||||
Déjà Fu has been produced as part of my Ph.D work, and wouldn't be
|
||||
possible without prior research. Here are the core papers:
|
||||
|
||||
* Bounded partial-order reduction, K. Coons, M. Musuvathi,
|
||||
and K. McKinley (2013)
|
||||
* Dynamic Partial Order Reduction for Relaxed Memory
|
||||
Models, N. Zhang, M. Kusano, and C. Wang (2015)
|
||||
* Concurrency Testing Using Schedule Bounding: an Empirical
|
||||
Study, P. Thompson, A. Donaldson, and A. Betts (2014)
|
||||
* On the Verification of Programs on Relaxed Memory
|
||||
Models, A. Linden (2014)
|
||||
70
doc/ghc.rst
70
doc/ghc.rst
@ -1,70 +0,0 @@
|
||||
Supported GHC Versions
|
||||
======================
|
||||
|
||||
Déjà Fu supports the latest four GHC releases, at least. For testing
|
||||
purposes, we use Stackage snapshots as a proxy for GHC versions. The
|
||||
currently supported versions are:
|
||||
|
||||
.. csv-table::
|
||||
:header: "GHC", "Stackage", "base"
|
||||
|
||||
"9.6", "Nightly 2021-07-01", "4.18.0.0"
|
||||
"9.4", "LTS 21.0", "4.17.0.0"
|
||||
"9.2", "LTS 20.0", "4.16.0.0"
|
||||
"9.0", "LTS 19.0", "4.15.0.0"
|
||||
"8.10", "LTS 17.0", "4.14.1.0"
|
||||
"8.8", "LTS 15.0", "4.13.0.0"
|
||||
"8.6", "LTS 14.0", "4.12.0.0"
|
||||
"8.4", "LTS 12.0", "4.11.0.0"
|
||||
"8.2", "LTS 10.0", "4.10.1.0"
|
||||
|
||||
In practice, we may *compile with* older versions of GHC, but keeping
|
||||
them working is not a priority.
|
||||
|
||||
|
||||
Adding new GHC releases
|
||||
-----------------------
|
||||
|
||||
When a new version of GHC is released, we need to make some changes
|
||||
for everything to go smoothly. In general, these changes should only
|
||||
cause a **patch level version bump**.
|
||||
|
||||
1. Bump the upper bound of :hackage:`base` and set up any needed
|
||||
conditional compilation
|
||||
2. Add the GHC and base versions to the table.
|
||||
3. Remove any unsupported versions from the table.
|
||||
4. Make a patch release.
|
||||
|
||||
A new GHC release won't get a Stackage snapshot for little while. When it
|
||||
does:
|
||||
|
||||
1. Add the snapshot to the GitHub Actions configuration.
|
||||
2. Update the resolver in the stack.yaml.
|
||||
3. Put the snapshot in the table.
|
||||
|
||||
|
||||
Dropping old GHC releases
|
||||
-------------------------
|
||||
|
||||
When we want to drop an unsupported version of GHC, we need to bump
|
||||
the version bound on :hackage:`base` to preclude it. This is a
|
||||
backwards-incompatible change which causes a **major version bump**.
|
||||
|
||||
1. Remove the dropped GHC version from the GitHub Actions
|
||||
configuration.
|
||||
2. Bump the lower bound of :hackage:`base`.
|
||||
3. Look through the other dependencies. Some may not work with our
|
||||
new lower bound on :hackage:`base`, so we should bump those too.
|
||||
4. Remove any now-irrelevant conditional compilation (mostly CPP, but
|
||||
there may also be some cabal file bits).
|
||||
5. Make whatever change required the bump.
|
||||
6. Make a major release.
|
||||
|
||||
GHC versions shouldn't be dropped just because we can, but here are
|
||||
some good reasons to do it:
|
||||
|
||||
* We want to bump the lower bounds of a dependency to a version which
|
||||
doesn't support that GHC.
|
||||
* We want to add a new dependency which doesn't support that GHC.
|
||||
* The conditional compilation needed to keep that GHC working is
|
||||
getting confusing.
|
||||
@ -1,42 +0,0 @@
|
||||
This is Déjà Fu
|
||||
===============
|
||||
|
||||
[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**
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: User Documentation
|
||||
|
||||
getting_started
|
||||
typeclass
|
||||
unit_testing
|
||||
refinement_testing
|
||||
advanced
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Migration Guides
|
||||
|
||||
migration_1x_2x
|
||||
migration_0x_1x
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Developer Documentation
|
||||
|
||||
contributing
|
||||
ghc
|
||||
release_process
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Release Notes
|
||||
|
||||
concurrency <changelog_concurrency>
|
||||
dejafu <changelog_dejafu>
|
||||
hunit-dejafu <changelog_hunit-dejafu>
|
||||
tasty-dejafu <changelog_tasty-dejafu>
|
||||
@ -1,117 +0,0 @@
|
||||
0.x to 1.x
|
||||
==========
|
||||
|
||||
:hackage:`dejafu-1.0.0.0` is a super-major release which breaks
|
||||
compatibility with :hackage:`dejafu-0.x <dejafu-0.9.1.1>` quite
|
||||
significantly, but brings with it support for bound threads, and
|
||||
significantly improves memory usage in the general case.
|
||||
|
||||
Highlights reel:
|
||||
|
||||
* Most predicates now only need to keep around the failures, rather
|
||||
than all results.
|
||||
* Support for bound threads (with :hackage:`concurrency-1.3.0.0`).
|
||||
* The ``ST`` / ``IO`` interface duplication is gone, everything is now
|
||||
monadic.
|
||||
* Function parameter order is closer to other testing libraries.
|
||||
* Much improved API documentation.
|
||||
|
||||
See the changelogs for the full details.
|
||||
|
||||
|
||||
``ST`` and ``IO`` functions
|
||||
---------------------------
|
||||
|
||||
There is only one set of functions now. Testing bound threads
|
||||
requires being able to fork actual threads, so testing with ``ST`` is
|
||||
no longer possible. The ``ConcST`` type is gone, there is only
|
||||
``ConcIO``.
|
||||
|
||||
For :hackage:`dejafu` change:
|
||||
|
||||
* ``autocheckIO`` to ``autocheck``
|
||||
* ``dejafuIO`` to ``dejafu``
|
||||
* ``dejafusIO`` to ``dejafus``
|
||||
* ``autocheckWayIO`` to ``autocheckWay``
|
||||
* ``dejafuWayIO`` to ``dejafuWay``
|
||||
* ``dejafusWayIO`` to ``dejafusWay``
|
||||
* ``dejafuDiscardIO`` to ``dejafuDiscard``
|
||||
* ``runTestM`` to ``runTest``
|
||||
* ``runTestWayM`` to ``runTestWay``
|
||||
|
||||
If you relied on being able to get a pure result from the ``ConcST``
|
||||
functions, you can no longer do this.
|
||||
|
||||
For :hackage:`hunit-dejafu` and :hackage:`tasty-dejafu` change:
|
||||
|
||||
* ``testAutoIO`` to ``testAuto``
|
||||
* ``testDejafuIO`` to ``testDejafu``
|
||||
* ``testDejafusIO`` to ``testDejafus``
|
||||
* ``testAutoWayIO`` to ``testAutoWay``
|
||||
* ``testDejafuWayIO`` to ``testDejafuWay``
|
||||
* ``testDejafusWayIO`` to ``testDejafusWay``
|
||||
* ``testDejafuDiscardIO`` to ``testDejafuDiscard``
|
||||
|
||||
|
||||
Function parameter order
|
||||
------------------------
|
||||
|
||||
Like :hackage:`HUnit`, the monadic action to test is now the last
|
||||
parameter of the testing functions. This makes it convenient to write
|
||||
tests without needing to define the action elsewhere.
|
||||
|
||||
For :hackage:`dejafu` change:
|
||||
|
||||
* ``dejafu ma (s, p)`` to ``dejafu s p ma``
|
||||
* ``dejafus ma ps`` to ``dejafus ps ma``
|
||||
* ``dejafuWay way mem ma (s, p)`` to ``dejafuWay way mem s p ma``
|
||||
* ``dejafusWay way mem ma ps`` to ``dejafuWay way mem ps ma``
|
||||
* ``dejafuDiscard d way mem ma (s, p)`` to ``dejafuDiscard d way mem s p ma``
|
||||
|
||||
For :hackage:`hunit-dejafu` and :hackage:`tasty-dejafu` change:
|
||||
|
||||
* ``testDejafu ma s p`` to ``testDejafu s p ma``
|
||||
* ``testDejafus ma ps`` to ``testDejafus ps ma``
|
||||
* ``testDejafuWay way mem ma s p`` to ``testDejafuWay way mem s p ma``
|
||||
* ``testDejafusWay way mem ma ps`` to ``testDejafusWay way mem ps ma``
|
||||
* ``testDejafuDiscard d way mem ma s p`` to ``testDejafuDiscard d way mem s p ma``
|
||||
|
||||
|
||||
Predicates
|
||||
----------
|
||||
|
||||
The ``Predicate a`` type is now an alias for ``ProPredicate a a``,
|
||||
defined like so:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
data ProPredicate a b = ProPredicate
|
||||
{ pdiscard :: Either Failure a -> Maybe Discard
|
||||
-- ^ Selectively discard results before computing the result.
|
||||
, peval :: [(Either Failure a, Trace)] -> Result b
|
||||
-- ^ Compute the result with the un-discarded results.
|
||||
}
|
||||
|
||||
If you use the predicate helper functions to construct a predicate,
|
||||
you do not need to change anything (and should get a nice reduction in
|
||||
your resident memory usage). If you supply a function directly, you
|
||||
can recover the old behaviour like so:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
old :: ([(Either Failure a, Trace)] -> Result a) -> ProPredicate a a
|
||||
old p = ProPredicate
|
||||
{ pdiscard = const Nothing
|
||||
, peval = p
|
||||
}
|
||||
|
||||
The ``alwaysTrue2`` helper function is gone. If you use it, use
|
||||
``alwaysSameOn`` or ``alwaysSameBy`` instead.
|
||||
|
||||
|
||||
Need help?
|
||||
----------
|
||||
|
||||
* 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 :issue:`file an issue <>`.
|
||||
@ -1,116 +0,0 @@
|
||||
1.x to 2.x
|
||||
==========
|
||||
|
||||
:hackage:`dejafu-2.0.0.0` is a super-major release which breaks
|
||||
compatibility with :hackage:`dejafu-1.x <dejafu-1.12.0.0>`.
|
||||
|
||||
Highlights reel:
|
||||
|
||||
* Test cases are written in terms of a new ``Program`` type.
|
||||
* The ``Failure`` type has been replaced with a ``Condition`` type
|
||||
(actually in 1.12).
|
||||
* Random testing takes an optional length bound.
|
||||
* Atomically-checked invariants over shared mutable state.
|
||||
|
||||
See the changelogs for the full details.
|
||||
|
||||
|
||||
The ``Program`` type
|
||||
--------------------
|
||||
|
||||
The ``ConcT`` type is now an alias for ``Program Basic``.
|
||||
|
||||
A ``Program Basic`` has all the instances ``ConcT`` did, defined using
|
||||
the ``~`` instance trick, so this shouldn't be a breaking change:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
instance (pty ~ Basic) => MonadTrans (Program pty)
|
||||
instance (pty ~ Basic) => MonadCatch (Program pty n)
|
||||
instance (pty ~ Basic) => MonadThrow (Program pty n)
|
||||
instance (pty ~ Basic) => MonadMask (Program pty n)
|
||||
instance (pty ~ Basic, Monad n) => MonadConc (Program pty n)
|
||||
instance (pty ~ Basic, MonadIO n) => MonadIO (Program pty n)
|
||||
|
||||
The ``dontCheck`` function has been removed in favour of
|
||||
``withSetup``:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
do x <- dontCheck setup
|
||||
action x
|
||||
|
||||
-- becomes
|
||||
|
||||
withSetup setup action
|
||||
|
||||
The ``subconcurrency`` function has been removed in favour of
|
||||
``withSetupAndTeardown``:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
do x <- setup
|
||||
y <- subconcurrency (action x)
|
||||
teardown x y
|
||||
|
||||
-- becomes
|
||||
|
||||
withSetupAndTeardown setup teardown action
|
||||
|
||||
The ``dontCheck`` and ``subconcurrency`` functions used to throw
|
||||
runtime errors if nested. This is not possible with ``withSetup`` and
|
||||
``withSetupAndTeardown`` due to their types:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
withSetup
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Program Basic n a)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetup x) n a
|
||||
|
||||
withSetupAndTeardown
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Either Condition y -> Program Basic n a)
|
||||
-- ^ Teardown action
|
||||
-> (x -> Program Basic n y)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetupAndTeardown x y) n a
|
||||
|
||||
Previously, multiple calls to ``subconcurrency`` could be sequenced in
|
||||
the same test case. This is not possible using
|
||||
``withSetupAndTeardown``. If you rely on this behaviour, please
|
||||
:issue:`file an issue <>`.
|
||||
|
||||
|
||||
The ``Condition`` type
|
||||
----------------------
|
||||
|
||||
This is a change in :hackage:`dejafu-1.12.0.0`, but the alias
|
||||
``Failure = Condition`` is removed in :hackage:`dejafu-2.0.0.0`.
|
||||
|
||||
* The ``STMDeadlock`` and ``Deadlock`` constructors have been merged.
|
||||
* Internal errors have been split into the ``Error`` type and are
|
||||
raised as exceptions, instead of being returned as conditions.
|
||||
|
||||
The name "failure" has been a recurring source of confusion, because
|
||||
an individual execution can "fail" without the predicate as a whole
|
||||
failing. My hope is that the more neutral "condition" will prevent
|
||||
this confusion.
|
||||
|
||||
|
||||
Deprecated functions
|
||||
--------------------
|
||||
|
||||
All the deprecated special-purpose functions have been removed. Use
|
||||
more general ``*WithSettings`` functions instead.
|
||||
|
||||
|
||||
Need help?
|
||||
----------
|
||||
|
||||
* 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 :issue:`file an issue <>`.
|
||||
@ -1,152 +0,0 @@
|
||||
Refinement Testing
|
||||
==================
|
||||
|
||||
Déjà Fu also supports a form of property-testing where you can check
|
||||
things about the side-effects of stateful operations. For example, we
|
||||
can assert that ``readMVar`` is equivalent to sequencing ``takeMVar``
|
||||
and ``putMVar`` like so:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
prop_mvar_read_take_put =
|
||||
sig readMVar `equivalentTo` sig (\v -> takeMVar v >>= putMVar v)
|
||||
|
||||
Given the signature function, ``sig``, defined in the next section.
|
||||
If we check this, our property fails!
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
> check prop_mvar_read_take_put
|
||||
*** Failure: (seed Just 0)
|
||||
left: [(Nothing,Just 0)]
|
||||
right: [(Nothing,Just 0),(Just Deadlock,Just 0)]
|
||||
False
|
||||
|
||||
This is because ``readMVar`` is atomic, whereas sequencing
|
||||
``takeMVar`` with ``putMVar`` is not, and so another thread can
|
||||
interfere with the ``MVar`` in the middle. The ``check`` and
|
||||
``equivalentTo`` functions come from ``Test.DejaFu.Refinement`` (also
|
||||
re-exported from ``Test.DejaFu``).
|
||||
|
||||
|
||||
Signatures
|
||||
----------
|
||||
|
||||
A signature tells the property-tester something about the state your
|
||||
operation acts upon, it has a few components:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
data Sig s o x = Sig
|
||||
{ initialise :: x -> ConcIO s
|
||||
, observe :: s -> x -> ConcIO o
|
||||
, interfere :: s -> x -> ConcIO ()
|
||||
, expression :: s -> ConcIO ()
|
||||
}
|
||||
|
||||
* ``s`` is the **state type**, it's the thing which your operations
|
||||
mutate. For ``readMVar``, the state is some ``MVar a``.
|
||||
|
||||
* ``o`` is the **observation type**, it's some pure (and comparable)
|
||||
proxy for a snapshot of your mutable state. For ``MVar a``, the
|
||||
observation is probably a ``Maybe a``.
|
||||
|
||||
* ``x`` is the **seed type**, it's some pure value used to construct
|
||||
the initial mutable state. For ``MVar a``, the seed is probably a
|
||||
``Maybe a``.
|
||||
|
||||
* ``ConcIO`` is just one of the instances of ``MonadConc`` that Déjà
|
||||
Fu defines for testing purposes. Just write code polymorphic in the
|
||||
monad as usual, and all will work.
|
||||
|
||||
The ``initialise``, ``observe``, and ``expression`` functions should
|
||||
be self-explanatory, but the ``interfere`` one may not be. It's the
|
||||
job of the ``interfere`` function to change the state in some way;
|
||||
it's run concurrently with the expression, to simulate the
|
||||
nondeterministic action of other threads.
|
||||
|
||||
Here's a concrete example for our ``MVar`` example:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
sig :: (MVar ConcIO Int -> ConcIO a) -> Sig (MVar ConcIO Int) (Maybe Int) (Maybe Int)
|
||||
sig e = Sig
|
||||
{ initialise = maybe newEmptyMVar newMVar
|
||||
, observe = \v _ -> tryTakeMVar v
|
||||
, interfere = \v s -> tryTakeMVar v >> maybe (pure ()) (\x -> void $ tryPutMVar v (x * 1000)) s
|
||||
, expression = void . e
|
||||
}
|
||||
|
||||
The ``observe`` function should be deterministic, but as it is run
|
||||
after the normal execution ends, it may have side-effects on the
|
||||
state. The ``interfere`` function can do just about anything [#]_,
|
||||
but a poor one may result in the property-checker being unable to
|
||||
distinguish between atomic and nonatomic expressions.
|
||||
|
||||
.. [#] There are probably some concrete rules for a good function, but
|
||||
I haven't figured them out yet.
|
||||
|
||||
|
||||
Properties
|
||||
----------
|
||||
|
||||
A property is a pair of signatures linked by one of three provided
|
||||
functions. These functions are:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Function", "Operator", "Checks that..."
|
||||
|
||||
"``equivalentTo``", "``===``", "... the left and right have exactly the same behaviours"
|
||||
"``refines``", "``=>=``", "... every behaviour of the left is also a behaviour of the right"
|
||||
"``strictlyRefines``", "``->-``", "... ``left =>= right`` holds but ``left === right`` does not"
|
||||
|
||||
The signatures can have different state types, as long as the seed and
|
||||
observation types are the same. This lets you compare different
|
||||
implementations of the same idea: for example, comparing a concurrent
|
||||
stack implemented using ``MVar`` with one implemented using ``IORef``.
|
||||
|
||||
Properties can have parameters, given in the obvious way:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
check $ \a b c -> sig1 ... `op` sig2 ...
|
||||
|
||||
Under the hood, seed and parameter values are generated using the
|
||||
:hackage:`leancheck` package, an enumerative property-based testing
|
||||
library. This means that any types you use will need to have a
|
||||
``Listable`` instance.
|
||||
|
||||
You can also think about the three functions in terms of sets of
|
||||
results, where a result is a ``(Maybe Failure, o)`` value. A
|
||||
``Failure`` is something like deadlocking, or being killed by an
|
||||
exception; ``o`` is the observation type. An observation is always
|
||||
made, even if execution of the expression fails.
|
||||
|
||||
.. csv-table::
|
||||
:header: "Function", "Result-set operation"
|
||||
|
||||
"``refines``", "For all seed and parameter assignments, subset-or-equal"
|
||||
"``strictlyRefines``", "For at least one seed and parameter assignment, proper subset; for all others, subset-or-equal"
|
||||
"``equivalentTo``", "For all seed and parameter assignments, equality"
|
||||
|
||||
Finally, there is an ``expectFailure`` function, which inverts the
|
||||
expected result of a property.
|
||||
|
||||
The Déjà Fu testsuite has :github:`a collection of refinement
|
||||
properties
|
||||
<blob/2a15549d97c2fa12f5e8b92ab918fdb34da78281/dejafu-tests/Cases/Refinement.hs>`,
|
||||
which may help you get a feel for this sort of testing.
|
||||
|
||||
|
||||
Using HUnit and Tasty
|
||||
---------------------
|
||||
|
||||
As for unit testing, :hackage:`HUnit` and :hackage:`tasty` integration
|
||||
is provided for refinement testing in the :hackage:`hunit-dejafu` and
|
||||
:hackage:`tasty-dejafu` packages.
|
||||
|
||||
The ``testProperty`` function is used to check properties. Our example from the start becomes:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
testProperty "Read is equivalent to Take then Put" prop_mvar_read_take_put
|
||||
@ -1,64 +0,0 @@
|
||||
Release Process
|
||||
===============
|
||||
|
||||
1. Figure out what the next version number is. See the PVP_ page if
|
||||
unsure.
|
||||
|
||||
2. Update version numbers in the relevant cabal files:
|
||||
|
||||
* Update the ``version`` field
|
||||
* Update the ``tag`` in the ``source-repository`` block
|
||||
|
||||
3. Fill in all ``@since unreleased`` Haddock comments with the
|
||||
relevant version number.
|
||||
|
||||
4. Update version numbers in the tables in the README and the Getting
|
||||
Started page.
|
||||
|
||||
5. Ensure the relevant CHANGELOG files have all the entries they
|
||||
should.
|
||||
|
||||
6. Add the release information to the relevant CHANGELOG files:
|
||||
|
||||
* Change the ``unreleased`` title to the version number
|
||||
* Add the current date
|
||||
|
||||
**If it's early in the year (like January or February), make sure
|
||||
you don't put down the wrong year.**
|
||||
|
||||
* Add the git tag name
|
||||
* Add the Hackage URL
|
||||
* Add the contributors list
|
||||
|
||||
7. Commit.
|
||||
|
||||
8. Push to GitHub and wait for GitHub Actions to confirm everything is
|
||||
OK. If it's not OK, fix what is broken before continuing.
|
||||
|
||||
9. Merge the PR.
|
||||
|
||||
10. Tag the merge commit. Tags are in the form
|
||||
``<package>-<version>``, and the message is the changelog entry.
|
||||
|
||||
11. Push tags to GitHub.
|
||||
|
||||
When the merge commit successfully builds on ``master`` the updated
|
||||
packages will be pushed to Hackage by Concourse.
|
||||
|
||||
|
||||
Pro tips
|
||||
--------
|
||||
|
||||
* If a release would have a combination of breaking and non-breaking
|
||||
changes, if possible make two releases: the non-breaking ones first,
|
||||
and then a major release with the breaking ones.
|
||||
|
||||
This makes it possible for users who don't want the breaking changes
|
||||
to still benefit from the non-breaking improvements.
|
||||
|
||||
* Before uploading to Hackage, check you have no changes to the files
|
||||
(for example, temporarily changing the GHC options, or adding
|
||||
``trace`` calls, for debugging reasons).
|
||||
|
||||
``stack upload`` will upload the files on the disk, not the files in
|
||||
version control, so your unwanted changes will be published!
|
||||
@ -1,115 +0,0 @@
|
||||
Typeclasses
|
||||
===========
|
||||
|
||||
We don't use the regular ``Control.Concurrent`` and
|
||||
``Control.Exception`` modules, we use typeclass-generalised ones
|
||||
instead from the :hackage:`concurrency` and :hackage:`exceptions`
|
||||
packages.
|
||||
|
||||
|
||||
Porting guide
|
||||
-------------
|
||||
|
||||
If you want to test some existing code, you'll need to port it to the
|
||||
appropriate typeclass. The typeclass is necessary, because we can't
|
||||
peek inside ``IO`` and ``STM`` values, so we need to able to plug in
|
||||
an alternative implementation when testing.
|
||||
|
||||
Fortunately, this tends to be a fairly mechanical and type-driven
|
||||
process:
|
||||
|
||||
1. Import ``Control.Concurrent.Classy.*`` instead of
|
||||
``Control.Concurrent.*``
|
||||
|
||||
2. Import ``Control.Monad.Catch`` instead of ``Control.Exception``
|
||||
|
||||
3. Change your monad type:
|
||||
|
||||
* ``IO a`` becomes ``MonadConc m => m a``
|
||||
* ``STM a`` becomes ``MonadSTM stm => stm a``
|
||||
|
||||
4. Parameterise your state types by the monad:
|
||||
|
||||
* ``TVar`` becomes ``TVar stm``
|
||||
* ``MVar`` becomes ``MVar m``
|
||||
* ``IORef`` becomes ``IORef m``
|
||||
|
||||
5. Some functions are renamed:
|
||||
|
||||
* ``forkIO*`` becomes ``fork*``
|
||||
* ``atomicModifyIORefCAS*`` becomes ``modifyIORefCAS*``
|
||||
|
||||
6. Fix the type errors
|
||||
|
||||
If you're lucky enough to be starting a new concurrent Haskell
|
||||
project, you can just program against the ``MonadConc`` interface.
|
||||
|
||||
|
||||
What if I really need I/O?
|
||||
--------------------------
|
||||
|
||||
You can use ``MonadIO`` and ``liftIO`` with ``MonadConc``, for
|
||||
instance if you need to talk to a database (or just use some existing
|
||||
library which needs real I/O).
|
||||
|
||||
To test ``IO``-using code, there are some rules you need to follow:
|
||||
|
||||
1. Given the same set of scheduling decisions, your ``IO`` code must
|
||||
be deterministic [#]_
|
||||
|
||||
2. As dejafu can't inspect ``IO`` values, they should be kept small;
|
||||
otherwise dejafu may miss buggy interleavings
|
||||
|
||||
3. You absolutely cannot block on the action of another thread inside
|
||||
``IO``, or the test execution will just deadlock.
|
||||
|
||||
.. [#] This is only essential if you're using the systematic testing
|
||||
(the default). Nondeterministic ``IO`` won't break the random
|
||||
testing, it'll just make things more confusing.
|
||||
|
||||
|
||||
Deriving your own instances
|
||||
---------------------------
|
||||
|
||||
There are ``MonadConc`` and ``MonadSTM`` instances for many common
|
||||
monad transformers. In the simple case, where you want an instance
|
||||
for a newtype wrapper around a type that has an instance, you may be
|
||||
able to derive it. For example:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
|
||||
{-# LANGUAGE StandaloneDeriving #-}
|
||||
{-# LANGUAGE UndecidableInstances #-}
|
||||
|
||||
data Env = Env
|
||||
|
||||
newtype MyMonad m a = MyMonad { runMyMonad :: ReaderT Env m a }
|
||||
deriving (Functor, Applicative, Monad)
|
||||
|
||||
deriving instance MonadThrow m => MonadThrow (MyMonad m)
|
||||
deriving instance MonadCatch m => MonadCatch (MyMonad m)
|
||||
deriving instance MonadMask m => MonadMask (MyMonad m)
|
||||
|
||||
deriving instance MonadConc m => MonadConc (MyMonad m)
|
||||
|
||||
``MonadSTM`` needs a slightly different set of classes:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
|
||||
{-# LANGUAGE StandaloneDeriving #-}
|
||||
{-# LANGUAGE UndecidableInstances #-}
|
||||
|
||||
data Env = Env
|
||||
|
||||
newtype MyMonad m a = MyMonad { runMyMonad :: ReaderT Env m a }
|
||||
deriving (Functor, Applicative, Monad, Alternative, MonadPlus)
|
||||
|
||||
deriving instance MonadThrow m => MonadThrow (MyMonad m)
|
||||
deriving instance MonadCatch m => MonadCatch (MyMonad m)
|
||||
|
||||
deriving instance MonadSTM m => MonadSTM (MyMonad m)
|
||||
|
||||
Don't be put off by the use of ``UndecidableInstances``, it's safe
|
||||
here.
|
||||
@ -1,250 +0,0 @@
|
||||
Unit Testing
|
||||
============
|
||||
|
||||
Writing tests with Déjà Fu is a little different to traditional unit
|
||||
testing, as your test case may have multiple results. A "test" is a
|
||||
combination of your code, and a predicate which says something about
|
||||
the set of allowed results.
|
||||
|
||||
Most tests will look something like this:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
dejafu "Assert the thing holds" myPredicate myAction
|
||||
|
||||
The ``dejafu`` function comes from ``Test.DejaFu``. Another useful
|
||||
function is ``dejafuWithSettings``; see :ref:`settings`.
|
||||
|
||||
|
||||
Actions
|
||||
-------
|
||||
|
||||
An action is just something with the type ``MonadConc m => m a``, or
|
||||
``(MonadConc m, MonadIO m) => m a`` for some ``a`` that your chosen
|
||||
predicate can deal with.
|
||||
|
||||
For example, some users on Reddit found a couple of apparent bugs in
|
||||
the :hackage:`auto-update` package a while ago (`thread here`__). As
|
||||
the package is simple and self-contained, I translated it to the
|
||||
``MonadConc`` abstraction and wrote a couple of tests to replicate the
|
||||
bugs. Here they are:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
deadlocks :: MonadConc m => m ()
|
||||
deadlocks = do
|
||||
auto <- mkAutoUpdate defaultUpdateSettings
|
||||
auto
|
||||
|
||||
nondeterministic :: forall m. MonadConc m => m Int
|
||||
nondeterministic = do
|
||||
var <- newIORef 0
|
||||
let settings = (defaultUpdateSettings :: UpdateSettings m ())
|
||||
{ updateAction = atomicModifyIORef var (\x -> (x+1, x)) }
|
||||
auto <- mkAutoUpdate settings
|
||||
auto
|
||||
auto
|
||||
|
||||
.. __: https://www.reddit.com/r/haskell/comments/2i5d7m/updating_autoupdate/
|
||||
|
||||
These actions action could be tested with ``autocheck``, and the
|
||||
issues would be revealed. The use of ``ScopedTypeVariables`` in the
|
||||
second is an unfortunate example of what can happen when everything
|
||||
becomes more polymorphic. But other than that, note how there is no
|
||||
special mention of Déjà Fu in the actions: it's just normal concurrent
|
||||
Haskell, simply written against a different interface.
|
||||
|
||||
The modified package is included :github:`in the test suite
|
||||
<blob/2a15549d97c2fa12f5e8b92ab918fdb34da78281/dejafu-tests/Examples/AutoUpdate.hs>`,
|
||||
if you want to see the full code. [#]_
|
||||
|
||||
.. [#] The predicates in dejafu-tests are a little confusing, as
|
||||
they're the opposite of what you would normally write! These
|
||||
predicates are checking that the bug is found, not that the
|
||||
code is correct.
|
||||
|
||||
If the RTS supports bound threads (the ``-threaded`` flag was passed
|
||||
to GHC when linking), then the main thread of an action given to Déjà
|
||||
Fu will be bound, and further bound threads can be forked with the
|
||||
``forkOS`` functions. If not, then attempting to fork a bound thread
|
||||
will raise an error.
|
||||
|
||||
|
||||
Conditions
|
||||
----------
|
||||
|
||||
When a concurrent program of type ``MonadConc m => m a`` is executed,
|
||||
it may produce a value of type ``a``, or it may experience a
|
||||
**condition** such as deadlock.
|
||||
|
||||
A condition does not necessarily cause your test to fail. It's
|
||||
important to be aware of what exactly your test is testing, to avoid
|
||||
drawing the wrong conclusions from a passing (or failing) test.
|
||||
|
||||
|
||||
Setup and Teardown
|
||||
------------------
|
||||
|
||||
Because dejafu drives the execution of the program under test, there
|
||||
are some tricks available to you which are not possible using normal
|
||||
concurrent Haskell.
|
||||
|
||||
If your test does some set-up work which is required for your test to
|
||||
work, but which is not the actual thing you are testing, you can
|
||||
define that as a **setup action**:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
withSetup
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Program Basic n a)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetup x) n a
|
||||
|
||||
dejafu will save the state at the end of the setup action, and
|
||||
efficiently restore that state in subsequent runs of the same test
|
||||
with a different schedule. This can be much more efficient than
|
||||
dejafu running the setup action normally every single time.
|
||||
|
||||
If you want to examine some state you created in your setup action
|
||||
even if your actual test case deadlocks or something, you can define a
|
||||
**teardown action**:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
withSetupAndTeardown
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Either Condition y -> Program Basic n a)
|
||||
-- ^ Teardown action
|
||||
-> (x -> Program Basic n y)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetupAndTeardown x y) n a
|
||||
|
||||
The teardown action is always executed.
|
||||
|
||||
Finally, if you want to ensure that some invariant holds over some
|
||||
shared state, you can define invariants in the setup action, which are
|
||||
checked atomically during the main action:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
-- slightly contrived example
|
||||
let setup = do
|
||||
var <- newEmptyMVar
|
||||
registerInvariant $ do
|
||||
value <- inspectMVar var
|
||||
when (x == Just 1) (throwM Overflow)
|
||||
pure var
|
||||
in withSetup setup $ \var -> do
|
||||
fork $ putMVar var 0
|
||||
fork $ putMVar var 1
|
||||
tryReadMVar var
|
||||
|
||||
If the main action violates the invariant, it is terminated with an
|
||||
``InvariantFailure`` condition, and any teardown action is run.
|
||||
|
||||
|
||||
Predicates
|
||||
----------
|
||||
|
||||
There are a few predicates built in, and some helpers to define your
|
||||
own.
|
||||
|
||||
.. csv-table::
|
||||
:widths: 25, 75
|
||||
|
||||
``abortsNever``,"checks that the computation never aborts"
|
||||
``abortsAlways``,"checks that the computation always aborts"
|
||||
``abortsSometimes``,"checks that the computation aborts at least once"
|
||||
|
||||
An **abort** is where the scheduler chooses to terminate execution
|
||||
early. If you see it, it probably means that a test didn't terminate
|
||||
before it hit the execution length limit. Aborts are hidden unless
|
||||
you use explicitly enable them, see :ref:`settings`.
|
||||
|
||||
.. csv-table::
|
||||
:widths: 25, 75
|
||||
|
||||
``deadlocksNever``,"checks that the computation never deadlocks"
|
||||
``deadlocksAlways``,"checks that the computation always deadlocks"
|
||||
``deadlocksSometimes``,"checks that the computation deadlocks at least once"
|
||||
|
||||
**Deadlocking** is where every thread becomes blocked. This can be,
|
||||
for example, if every thread is trying to read from an ``MVar`` that
|
||||
has been emptied.
|
||||
|
||||
.. csv-table::
|
||||
:widths: 25, 75
|
||||
|
||||
``exceptionsNever``,"checks that the main thread is never killed by an exception"
|
||||
``exceptionsAlways``,"checks that the main thread is always killed by an exception"
|
||||
``exceptionsSometimes``,"checks that the main thread is killed by an exception at least once"
|
||||
|
||||
An uncaught **exception** in the main thread kills the process. These
|
||||
can be synchronous (thrown in the main thread) or asynchronous (thrown
|
||||
to it from a different thread).
|
||||
|
||||
.. csv-table::
|
||||
:widths: 25, 75
|
||||
|
||||
``alwaysSame``,"checks that the computation is deterministic and always produces a value"
|
||||
``alwaysSameOn f``,"is like ``alwaysSame``, but transforms the results with ``f`` first"
|
||||
``alwaysSameBy f``,"is like ``alwaysSame``, but uses ``f`` instead of ``(==)`` to compare"
|
||||
``notAlwaysSame``,"checks that the computation is nondeterministic"
|
||||
``notAlwaysSameOn f``,"is like ``notAlwaysSame``, but transforms the results with ``f`` first"
|
||||
``notAlwaysSameBy f``,"is like ``notAlwaysSame``, but uses ``f`` instead of ``(==)`` to compare"
|
||||
|
||||
Checking for **determinism** will also find nondeterministic failures:
|
||||
deadlocking (for instance) is still a result of a test!
|
||||
|
||||
.. csv-table::
|
||||
:widths: 25, 75
|
||||
|
||||
``alwaysTrue p``,"checks that ``p`` is true for every result"
|
||||
``somewhereTrue p``,"checks that ``p`` is true for at least one result"
|
||||
|
||||
These can be used to check custom predicates. For example, you might
|
||||
want all your results to be less than five.
|
||||
|
||||
.. csv-table::
|
||||
:widths: 25, 75
|
||||
|
||||
``gives xs``,"checks that the set of results is exactly ``xs`` (which may include conditions)"
|
||||
``gives' xs``,"checks that the set of results is exactly ``xs`` (which may not include conditions)"
|
||||
|
||||
These let you say exactly what you want the results to be. Your test
|
||||
will fail if it has any extra results, or misses a result.
|
||||
|
||||
You can check multiple predicates against the same collection of
|
||||
results using the ``dejafus`` and ``dejafusWithSettings`` functions.
|
||||
These avoid recomputing the results, and so may be faster than
|
||||
multiple ``dejafu`` / ``dejafuWithSettings`` calls; see
|
||||
:ref:`performance`.
|
||||
|
||||
|
||||
Using HUnit and Tasty
|
||||
---------------------
|
||||
|
||||
By itself, Déjà Fu has no framework in place for named test groups and
|
||||
parallel execution or anything like that. It does one thing and does
|
||||
it well, which is running test cases for concurrent programs.
|
||||
:hackage:`HUnit` and :hackage:`tasty` integration is provided to get
|
||||
more of the features you'd expect from a testing framework.
|
||||
|
||||
The integration is provided by the :hackage:`hunit-dejafu` and
|
||||
:hackage:`tasty-dejafu` packages.
|
||||
|
||||
There's a simple naming convention used: the ``Test.DejaFu`` function
|
||||
``dejafuFoo`` is wrapped in the appropriate way and exposed as
|
||||
``testDejafuFoo`` from ``Test.HUnit.DejaFu`` and
|
||||
``Test.Tasty.DejaFu``.
|
||||
|
||||
Our example from the start becomes:
|
||||
|
||||
.. code-block:: haskell
|
||||
|
||||
testDejafu "Assert the thing holds" myPredicate myAction
|
||||
|
||||
The ``autocheck`` function is exposed as ``testAuto``.
|
||||
9
docs/.gitignore
vendored
Normal file
9
docs/.gitignore
vendored
Normal file
@ -0,0 +1,9 @@
|
||||
book
|
||||
|
||||
# generated by the build script
|
||||
src/index.md
|
||||
src/release-notes/concurrency.md
|
||||
src/release-notes/dejafu.md
|
||||
src/release-notes/hunit-dejafu.md
|
||||
src/release-notes/tasty-dejafu.md
|
||||
mdbook-admonish.css
|
||||
17
docs/book.toml
Normal file
17
docs/book.toml
Normal file
@ -0,0 +1,17 @@
|
||||
[book]
|
||||
title = "Déjà Fu"
|
||||
authors = ["Michael Walker (barrucadu)"]
|
||||
description = "Systematic concurrency testing meets Haskell."
|
||||
language = "en"
|
||||
multilingual = false
|
||||
|
||||
[build]
|
||||
create-missing = false
|
||||
|
||||
[output.html]
|
||||
git-repository-url = "https://github.com/barrucadu/dejafu"
|
||||
cname = "dejafu.docs.barrucadu.co.uk"
|
||||
|
||||
[preprocessor.admonish]
|
||||
on_failure = "bail"
|
||||
command = "mdbook-admonish"
|
||||
@ -1,12 +1,12 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXPROJ = DjFu
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@ -17,4 +17,4 @@ help:
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
2
docs/readthedocs/requirements.txt
Normal file
2
docs/readthedocs/requirements.txt
Normal file
@ -0,0 +1,2 @@
|
||||
sphinx==7.1.2
|
||||
sphinx-rtd-theme==1.3.0rc1
|
||||
23
docs/readthedocs/source/conf.py
Normal file
23
docs/readthedocs/source/conf.py
Normal file
@ -0,0 +1,23 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
|
||||
# -- Project information
|
||||
|
||||
project = 'Déjà Fu'
|
||||
copyright = 'Michael Walker (barrucadu)'
|
||||
author = 'Michael Walker (barrucadu)'
|
||||
|
||||
release = 'HEAD'
|
||||
version = 'HEAD'
|
||||
|
||||
# -- General configuration
|
||||
|
||||
extensions = []
|
||||
|
||||
templates_path = ['_templates']
|
||||
|
||||
# -- Options for HTML output
|
||||
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# -- Options for EPUB output
|
||||
epub_show_urls = 'footnote'
|
||||
10
docs/readthedocs/source/index.rst
Normal file
10
docs/readthedocs/source/index.rst
Normal file
@ -0,0 +1,10 @@
|
||||
The Déjà Fu documentation has moved!
|
||||
====================================
|
||||
|
||||
[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**
|
||||
|
||||
`Visit the new documentation website <https://dejafu.docs.barrucadu.co.uk/>`.
|
||||
25
docs/src/SUMMARY.md
Normal file
25
docs/src/SUMMARY.md
Normal file
@ -0,0 +1,25 @@
|
||||
# Summary
|
||||
|
||||
- [Getting Started](./index.md)
|
||||
- [Typeclasses](./typeclasses.md)
|
||||
- [Unit Testing](./unit-testing.md)
|
||||
- [Refinement Testing](./refinement-testing.md)
|
||||
- [Advanced Usage](./advanced-usage.md)
|
||||
|
||||
# Migration Guides
|
||||
|
||||
- [1.x to 2.x](./migration-guides/1x-2x.md)
|
||||
- [0.x to 1.x](./migration-guides/0x-1x.md)
|
||||
|
||||
# Developer Documentation
|
||||
|
||||
- [Contributing](./dev-docs/contributing.md)
|
||||
- [Supported GHC Versions](./dev-docs/supported-ghc-versions.md)
|
||||
- [Release Process](./dev-docs/release-process.md)
|
||||
|
||||
# Release Notes
|
||||
|
||||
- [concurrency](./release-notes/concurrency.md)
|
||||
- [dejafu](./release-notes/dejafu.md)
|
||||
- [hunit-dejafu](./release-notes/hunit-dejafu.md)
|
||||
- [tasty-dejafu](./release-notes/tasty-dejafu.md)
|
||||
96
docs/src/advanced-usage.md
Normal file
96
docs/src/advanced-usage.md
Normal file
@ -0,0 +1,96 @@
|
||||
Advanced Usage
|
||||
==============
|
||||
|
||||
Déjà Fu tries to have a sensible set of defaults, but there are some
|
||||
times when the defaults are not suitable. There are a lot of knobs
|
||||
provided to tweak how things work.
|
||||
|
||||
|
||||
Execution settings
|
||||
------------------
|
||||
|
||||
The `autocheckWithSettings`, `dejafuWithSettings`, and `dejafusWithSettings` let
|
||||
you provide a `Settings` value, which controls some of Déjà Fu's behaviour:
|
||||
|
||||
```haskell
|
||||
dejafuWithSettings mySettings "Assert the thing holds" myPredicate myAction
|
||||
```
|
||||
|
||||
The available settings are:
|
||||
|
||||
- **"Way"**, how to explore the behaviours of the program under test.
|
||||
|
||||
- **Length bound**, a cut-off point to terminate an execution even if it's not
|
||||
done yet.
|
||||
|
||||
- **Memory model**, which affects how non-synchronised operations, such as
|
||||
`readIORef` and `writeIORef` behave.
|
||||
|
||||
- **Discarding**, which allows throwing away uninteresting results, rather than
|
||||
keeping them around in memory.
|
||||
|
||||
- **Early exit**, which allows exiting as soon as a result matching a predicate
|
||||
is found.
|
||||
|
||||
- **Representative traces**, keeping only one execution trace for each distinct
|
||||
result.
|
||||
|
||||
- **Trace simplification**, rewriting execution traces into a simpler form
|
||||
(particularly effective with the random testing).
|
||||
|
||||
- **Safe IO**, pruning needless schedules when your IO is only used to manage
|
||||
thread-local state.
|
||||
|
||||
See the `Test.DejaFu.Settings` module for more information.
|
||||
|
||||
|
||||
Performance tuning
|
||||
------------------
|
||||
|
||||
- Are you happy to trade space for time?
|
||||
|
||||
Consider computing the results once and running multiple predicates over the
|
||||
output: this is what `dejafus` / `testDejafus` / etc does.
|
||||
|
||||
- Can you sacrifice completeness?
|
||||
|
||||
Consider using the random testing functionality. See the `*WithSettings`
|
||||
functions.
|
||||
|
||||
- Would strictness help?
|
||||
|
||||
Consider using the strict functions in `Test.DejaFu.SCT` (the ones ending
|
||||
with a `'`).
|
||||
|
||||
- Do you just want the set of results, and don't care about traces?
|
||||
|
||||
Consider using `Test.DejaFu.SCT.resultsSet`.
|
||||
|
||||
- Do you know something about the sort of results you care about?
|
||||
|
||||
Consider discarding results you *don't* care about. See the `*WithSettings`
|
||||
functions in `Test.DejaFu`, `Test.DejaFu.SCT`, and
|
||||
`Test.{HUnit,Tasty}.DejaFu`.
|
||||
|
||||
For example, let's say you want to know if your test case deadlocks, but you
|
||||
don't care about the execution trace, and you are going to sacrifice
|
||||
completeness because your possible state-space is huge. You could do it like
|
||||
this:
|
||||
|
||||
```haskell
|
||||
dejafuWithSettings
|
||||
( set ldiscard
|
||||
-- "efa" == "either failure a", discard everything but deadlocks
|
||||
(Just $ \efa -> Just (if either isDeadlock (const False) efa then DiscardTrace else DiscardResultAndTrace))
|
||||
. set lway
|
||||
-- try 10000 executions with random scheduling
|
||||
(randomly (mkStdGen 42) 10000)
|
||||
$ defaultSettings
|
||||
)
|
||||
-- the name of the test
|
||||
"Never Deadlocks"
|
||||
-- the predicate to check
|
||||
deadlocksNever
|
||||
-- your test case
|
||||
testCase
|
||||
```
|
||||
221
docs/src/dev-docs/contributing.md
Normal file
221
docs/src/dev-docs/contributing.md
Normal file
@ -0,0 +1,221 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
Thanks for caring about Déjà Fu!
|
||||
|
||||
|
||||
Ways to contribute
|
||||
------------------
|
||||
|
||||
Déjà Fu is a project under active development, there's always something to do.
|
||||
Here's a list of ideas to get you started:
|
||||
|
||||
- Submit bug reports.
|
||||
- Submit feature requests.
|
||||
- Got a particularly slow test case which you think should be faster? Open an
|
||||
issue for that too.
|
||||
- Blog about how and why you use Déjà Fu.
|
||||
- Check if any bugs which have been open for a while are still bugs.
|
||||
|
||||
If you want to contribute code, you could:
|
||||
|
||||
- Tackle one of the issues tagged ["good first issue"][good-first-issue].
|
||||
- Tackle a bigger issue, perhaps one of the [roadmap issues][roadmap]!
|
||||
- Run code coverage and try to fix a gap in the tests.
|
||||
- Profile the test suite and try to improve a slow function.
|
||||
|
||||
[Roadmap issues][roadmap] are priority issues (in my opinion), so help with
|
||||
those is especially appreciated.
|
||||
|
||||
If you have a support question, you can talk to me on IRC (#haskell on freenode)
|
||||
or send an email (mike@barrucadu.co.uk) rather than opening an issue. But maybe
|
||||
your question is a bug report about poor documentation in disguise!
|
||||
|
||||
[good-first-issue]: https://github.com/barrucadu/dejafu/labels/good%20first%20issue
|
||||
[roadmap]: https://github.com/barrucadu/dejafu/labels/roadmap
|
||||
|
||||
|
||||
Making the change
|
||||
-----------------
|
||||
|
||||
1. Talk to me!
|
||||
|
||||
I don't bite, and chances are I can quickly tell you where you should start.
|
||||
It's better to ask what seems like a stupid question than to waste a lot of
|
||||
time on the wrong approach.
|
||||
|
||||
2. Make the change.
|
||||
|
||||
Figure out what needs to be changed, how to change it, and do it. If you're
|
||||
fixing a bug, make sure to add a minimal reproduction to Cases.Regressions in
|
||||
dejafu-tests.
|
||||
|
||||
3. Document the change.
|
||||
|
||||
All top-level definitions should have a [Haddock][] comment explaining what
|
||||
it does. If you've added or changed a top-level function, consider
|
||||
commenting its arguments too.
|
||||
|
||||
If you've added a top-level definition, or changed one in a
|
||||
backwards-incompatible way, add an `@since unreleased` Haddock comment to it.
|
||||
This is to help prevent me from missing things when I update the changelog
|
||||
ahead of a release.
|
||||
|
||||
4. Submit a PR.
|
||||
|
||||
GitHub Actions will run some checks, which might prompt further action. You
|
||||
should expect a response from me in a day or two.
|
||||
|
||||
Don't worry about your PR being perfect the first time. We'll work through any
|
||||
issues together, to ensure that Déjà Fu gets the best code it can.
|
||||
|
||||
[Haddock]: https://hackage.haskell.org/package/haddock
|
||||
|
||||
|
||||
Coding style
|
||||
------------
|
||||
|
||||
There isn't really a prescribed style. It's not quite the wild west though;
|
||||
keep these three rules in mind:
|
||||
|
||||
1. Be consistent.
|
||||
2. Run [stylish-haskell][] to format import lists.
|
||||
3. Use [hlint][] and [weeder][] and fix lints unless you
|
||||
have a good reason not to.
|
||||
|
||||
GitHub Actions runs stylish-haskell and hlint on all PRs.
|
||||
|
||||
[stylish-haskell]: https://hackage.haskell.org/package/stylish-haskell
|
||||
[hlint]: https://hackage.haskell.org/package/hlint
|
||||
[weeder]: https://hackage.haskell.org/package/weeder
|
||||
|
||||
|
||||
Coverage
|
||||
--------
|
||||
|
||||
[hpc][] can generate a coverage report from the execution of dejafu-tests:
|
||||
|
||||
```text
|
||||
$ stack build --coverage
|
||||
$ stack exec dejafu-tests
|
||||
$ stack hpc report --all dejafu-tests.tix
|
||||
```
|
||||
|
||||
This will print some stats and generate an HTML coverage report:
|
||||
|
||||
```text
|
||||
Generating combined report
|
||||
52% expressions used (4052/7693)
|
||||
48% boolean coverage (63/129)
|
||||
43% guards (46/106), 31 always True, 9 always False, 20 unevaluated
|
||||
68% 'if' conditions (11/16), 2 always True, 3 unevaluated
|
||||
85% qualifiers (6/7), 1 unevaluated
|
||||
61% alternatives used (392/635)
|
||||
80% local declarations used (210/261)
|
||||
26% top-level declarations used (280/1063)
|
||||
The combined report is available at /home/barrucadu/projects/dejafu/.stack-work/install/x86_64-linux/nightly-2016-06-20/8.0.1/hpc/combined/custom/hpc_index.html
|
||||
```
|
||||
|
||||
The highlighted code in the HTML report emphasises branch coverage:
|
||||
|
||||
- Red means a branch was evaluated as always false.
|
||||
- Green means a branch was evaluated as always true.
|
||||
- Yellow means an expression was never evaluated.
|
||||
|
||||
See also the [stack coverage documentation][cov].
|
||||
|
||||
[hpc]: https://wiki.haskell.org/Haskell_program_coverage
|
||||
[cov]: https://docs.haskellstack.org/en/latest/coverage/
|
||||
|
||||
|
||||
Performance
|
||||
-----------
|
||||
|
||||
GHC can generate performance statistics from the execution of dejafu-tests:
|
||||
|
||||
```text
|
||||
$ stack build --profile
|
||||
$ stack exec -- dejafu-tests +RTS -p
|
||||
$ less dejafu-tests.prof
|
||||
```
|
||||
|
||||
This prints a detailed breakdown of where memory and time are being spent:
|
||||
|
||||
```text
|
||||
Mon Mar 20 19:26 2017 Time and Allocation Profiling Report (Final)
|
||||
|
||||
dejafu-tests +RTS -p -RTS
|
||||
|
||||
total time = 105.94 secs (105938 ticks @ 1000 us, 1 processor)
|
||||
total alloc = 46,641,766,952 bytes (excludes profiling overheads)
|
||||
|
||||
COST CENTRE MODULE %time %alloc
|
||||
|
||||
findBacktrackSteps.doBacktrack.idxs' Test.DejaFu.SCT.Internal 21.9 12.0
|
||||
== Test.DejaFu.Common 12.4 0.0
|
||||
yieldCount.go Test.DejaFu.SCT 12.1 0.0
|
||||
dependent' Test.DejaFu.SCT 5.1 0.0
|
||||
runThreads.go Test.DejaFu.Conc.Internal 2.7 4.1
|
||||
[...]
|
||||
```
|
||||
|
||||
Be careful, however! Compiling with profiling can significantly affect the
|
||||
behaviour of a program! Use profiling to get an idea of where the hot spots
|
||||
are, but make sure to confirm with a non-profiled build that things are actually
|
||||
getting faster.
|
||||
|
||||
If you compile with `-rtsopts` you can get some basic stats from a non-profiled
|
||||
build:
|
||||
|
||||
```text
|
||||
$ stack exec -- dejafu-tests +RTS -s
|
||||
|
||||
[...]
|
||||
86,659,658,504 bytes allocated in the heap
|
||||
13,057,037,448 bytes copied during GC
|
||||
13,346,952 bytes maximum residency (4743 sample(s))
|
||||
127,824 bytes maximum slop
|
||||
37 MB total memory in use (0 MB lost due to fragmentation)
|
||||
|
||||
Tot time (elapsed) Avg pause Max pause
|
||||
Gen 0 78860 colls, 0 par 32.659s 32.970s 0.0004s 0.0669s
|
||||
Gen 1 4743 colls, 0 par 3.043s 3.052s 0.0006s 0.0086s
|
||||
|
||||
TASKS: 174069 (174065 bound, 4 peak workers (4 total), using -N1)
|
||||
|
||||
SPARKS: 0 (0 converted, 0 overflowed, 0 dud, 0 GC'd, 0 fizzled)
|
||||
|
||||
INIT time 0.001s ( 0.001s elapsed)
|
||||
MUT time 98.685s (101.611s elapsed)
|
||||
GC time 35.702s ( 36.022s elapsed)
|
||||
EXIT time 0.001s ( 0.007s elapsed)
|
||||
Total time 134.388s (137.640s elapsed)
|
||||
|
||||
Alloc rate 878,145,635 bytes per MUT second
|
||||
|
||||
Productivity 73.4% of total user, 73.8% of total elapsed
|
||||
```
|
||||
|
||||
|
||||
Heap profiling
|
||||
--------------
|
||||
|
||||
GHC can tell you where the memory is going:
|
||||
|
||||
```text
|
||||
$ stack build --profile
|
||||
$ stack exec -- dejafu-tests +RTS -hc
|
||||
$ hp2ps -c dejafu-tests.hp
|
||||
```
|
||||
|
||||
This will produce a graph of memory usage over time, as a postscript file,
|
||||
broken down by cost-centre which produced the data. There are a few different
|
||||
views:
|
||||
|
||||
- `-hm` breaks down the graph by module
|
||||
- `-hd` breaks down the graph by closure description
|
||||
- `-hy` breaks down the graph by type
|
||||
|
||||
I typically find `-hd` and `-hy` most useful. If you're feeling particularly
|
||||
brave, you can try `-hr`, which is intended to help track down memory leaks
|
||||
caused by unevaluated thunks.
|
||||
61
docs/src/dev-docs/release-process.md
Normal file
61
docs/src/dev-docs/release-process.md
Normal file
@ -0,0 +1,61 @@
|
||||
Release Process
|
||||
===============
|
||||
|
||||
```admonish warning
|
||||
If it's early in the year, make sure you put down the right year in the CHANGELOG!
|
||||
```
|
||||
|
||||
1. Figure out what the next version number is. See the PVP_ page if unsure.
|
||||
|
||||
2. Update version numbers in the relevant cabal files:
|
||||
|
||||
* Update the `version` field
|
||||
* Update the `tag` in the `source-repository` block
|
||||
|
||||
3. Fill in all `@since unreleased` Haddock comments with the relevant version
|
||||
number.
|
||||
|
||||
4. Update version numbers in the tables in the README page.
|
||||
|
||||
5. Ensure the relevant CHANGELOG files have all the entries they should.
|
||||
|
||||
6. Add the release information to the relevant CHANGELOG files:
|
||||
|
||||
* Change the `unreleased` title to the version number
|
||||
* Add the current date
|
||||
* Add the git tag name
|
||||
* Add the Hackage URL
|
||||
* Add the contributors list
|
||||
|
||||
7. Commit.
|
||||
|
||||
8. Push to GitHub and wait for GitHub Actions to confirm everything is
|
||||
OK. If it's not OK, fix what is broken before continuing.
|
||||
|
||||
9. Merge the PR.
|
||||
|
||||
10. Tag the merge commit. Tags are in the form `<package>-<version>`, and the
|
||||
message is the changelog entry.
|
||||
|
||||
11. Push tags to GitHub.
|
||||
|
||||
When the merge commit successfully builds on `master` the updated packages will
|
||||
be pushed to Hackage by Concourse.
|
||||
|
||||
|
||||
Pro tips
|
||||
--------
|
||||
|
||||
* If a release would have a combination of breaking and non-breaking changes, if
|
||||
possible make two releases: the non-breaking ones first, and then a major
|
||||
release with the breaking ones.
|
||||
|
||||
This makes it possible for users who don't want the breaking changes to still
|
||||
benefit from the non-breaking improvements.
|
||||
|
||||
* Before uploading to Hackage, check you have no changes to the files (for
|
||||
example, temporarily changing the GHC options, or adding `trace` calls, for
|
||||
debugging reasons).
|
||||
|
||||
`stack upload` will upload the files on the disk, not the files in version
|
||||
control, so your unwanted changes will be published!
|
||||
70
docs/src/dev-docs/supported-ghc-versions.md
Normal file
70
docs/src/dev-docs/supported-ghc-versions.md
Normal file
@ -0,0 +1,70 @@
|
||||
Supported GHC Versions
|
||||
======================
|
||||
|
||||
Déjà Fu supports the latest four GHC releases, at least. For testing purposes,
|
||||
we use Stackage snapshots as a proxy for GHC versions. The currently supported
|
||||
versions are:
|
||||
|
||||
| GHC | Stackage | base |
|
||||
| --- | -------- | ---- |
|
||||
| 9.6 | Nightly 2021-07-01 | 4.18.0.0 |
|
||||
| 9.4 | LTS 21.0 | 4.17.0.0 |
|
||||
| 9.2 | LTS 20.0 | 4.16.0.0 |
|
||||
| 9.0 | LTS 19.0 | 4.15.0.0 |
|
||||
| 8.1 |,LTS 17.0 | 4.14.1.0 |
|
||||
| 8.8 | LTS 15.0 | 4.13.0.0 |
|
||||
| 8.6 | LTS 14.0 | 4.12.0.0 |
|
||||
| 8.4 | LTS 12.0 | 4.11.0.0 |
|
||||
| 8.2 | LTS 10.0 | 4.10.1.0 |
|
||||
|
||||
In practice, we may *compile with* older versions of GHC, but keeping them
|
||||
working is not a priority.
|
||||
|
||||
|
||||
Adding new GHC releases
|
||||
-----------------------
|
||||
|
||||
When a new version of GHC is released, we need to make some changes for
|
||||
everything to go smoothly. In general, these changes should only cause a
|
||||
**patch level version bump**.
|
||||
|
||||
1. Bump the upper bound of [base][] and set up any needed conditional
|
||||
compilation
|
||||
2. Add the GHC and base versions to the table.
|
||||
3. Remove any unsupported versions from the table.
|
||||
4. Make a patch release.
|
||||
|
||||
A new GHC release won't get a Stackage snapshot for little while. When it
|
||||
does:
|
||||
|
||||
1. Add the snapshot to the GitHub Actions configuration.
|
||||
2. Update the resolver in the stack.yaml.
|
||||
3. Put the snapshot in the table.
|
||||
|
||||
|
||||
Dropping old GHC releases
|
||||
-------------------------
|
||||
|
||||
When we want to drop an unsupported version of GHC, we need to bump the version
|
||||
bound on [base][] to preclude it. This is a backwards-incompatible change which
|
||||
causes a **major version bump**.
|
||||
|
||||
1. Remove the dropped GHC version from the GitHub Actions configuration.
|
||||
2. Bump the lower bound of [base][].
|
||||
3. Look through the other dependencies. Some may not work with our new lower
|
||||
bound on [base][], so we should bump those too.
|
||||
4. Remove any now-irrelevant conditional compilation (mostly CPP, but there may
|
||||
also be some cabal file bits).
|
||||
5. Make whatever change required the bump.
|
||||
6. Make a major release.
|
||||
|
||||
GHC versions shouldn't be dropped just because we can, but here are some good
|
||||
reasons to do it:
|
||||
|
||||
- We want to bump the lower bounds of a dependency to a version which doesn't
|
||||
support that GHC.
|
||||
- We want to add a new dependency which doesn't support that GHC.
|
||||
- The conditional compilation needed to keep that GHC working is getting
|
||||
confusing.
|
||||
|
||||
[base]: https://hackage.haskell.org/package/base
|
||||
122
docs/src/migration-guides/0x-1x.md
Normal file
122
docs/src/migration-guides/0x-1x.md
Normal file
@ -0,0 +1,122 @@
|
||||
0.x to 1.x
|
||||
==========
|
||||
|
||||
[dejafu-1.0.0.0][] is a super-major release which breaks compatibility with
|
||||
[dejafu-0.x][] quite significantly, but brings with it support for bound
|
||||
threads, and significantly improves memory usage in the general case.
|
||||
|
||||
Highlights reel:
|
||||
|
||||
- Most predicates now only need to keep around the failures, rather than all
|
||||
results.
|
||||
- Support for bound threads (with [concurrency-1.3.0.0][]).
|
||||
- The `ST` / `IO` interface duplication is gone, everything is now monadic.
|
||||
- Function parameter order is closer to other testing libraries.
|
||||
- Much improved API documentation.
|
||||
|
||||
See the changelogs for the full details.
|
||||
|
||||
|
||||
`ST` and `IO` functions
|
||||
-----------------------
|
||||
|
||||
There is only one set of functions now. Testing bound threads requires being
|
||||
able to fork actual threads, so testing with `ST` is no longer possible. The
|
||||
`ConcST` type is gone, there is only `ConcIO`.
|
||||
|
||||
For [dejafu][] change:
|
||||
|
||||
- `autocheckIO` to `autocheck`
|
||||
- `dejafuIO` to `dejafu`
|
||||
- `dejafusIO` to `dejafus`
|
||||
- `autocheckWayIO` to `autocheckWay`
|
||||
- `dejafuWayIO` to `dejafuWay`
|
||||
- `dejafusWayIO` to `dejafusWay`
|
||||
- `dejafuDiscardIO` to `dejafuDiscard`
|
||||
- `runTestM` to `runTest`
|
||||
- `runTestWayM` to `runTestWay`
|
||||
|
||||
If you relied on being able to get a pure result from the `ConcST` functions,
|
||||
you can no longer do this.
|
||||
|
||||
For [hunit-dejafu][] and [tasty-dejafu][] change:
|
||||
|
||||
- `testAutoIO` to `testAuto`
|
||||
- `testDejafuIO` to `testDejafu`
|
||||
- `testDejafusIO` to `testDejafus`
|
||||
- `testAutoWayIO` to `testAutoWay`
|
||||
- `testDejafuWayIO` to `testDejafuWay`
|
||||
- `testDejafusWayIO` to `testDejafusWay`
|
||||
- `testDejafuDiscardIO` to `testDejafuDiscard`
|
||||
|
||||
|
||||
Function parameter order
|
||||
------------------------
|
||||
|
||||
Like [HUnit][], the monadic action to test is now the last parameter of the
|
||||
testing functions. This makes it convenient to write tests without needing to
|
||||
define the action elsewhere.
|
||||
|
||||
For [dejafu][] change:
|
||||
|
||||
- `dejafu ma (s, p)` to `dejafu s p ma`
|
||||
- `dejafus ma ps` to `dejafus ps ma`
|
||||
- `dejafuWay way mem ma (s, p)` to `dejafuWay way mem s p ma`
|
||||
- `dejafusWay way mem ma ps` to `dejafuWay way mem ps ma`
|
||||
- `dejafuDiscard d way mem ma (s, p)` to `dejafuDiscard d way mem s p ma`
|
||||
|
||||
For [hunit-dejafu][] and [tasty-dejafu][] change:
|
||||
|
||||
- `testDejafu ma s p` to `testDejafu s p ma`
|
||||
- `testDejafus ma ps` to `testDejafus ps ma`
|
||||
- `testDejafuWay way mem ma s p` to `testDejafuWay way mem s p ma`
|
||||
- `testDejafusWay way mem ma ps` to `testDejafusWay way mem ps ma`
|
||||
- `testDejafuDiscard d way mem ma s p` to `testDejafuDiscard d way mem s p ma`
|
||||
|
||||
|
||||
Predicates
|
||||
----------
|
||||
|
||||
The `Predicate a` type is now an alias for `ProPredicate a a`, defined like so:
|
||||
|
||||
```haskell
|
||||
data ProPredicate a b = ProPredicate
|
||||
{ pdiscard :: Either Failure a -> Maybe Discard
|
||||
-- ^ Selectively discard results before computing the result.
|
||||
, peval :: [(Either Failure a, Trace)] -> Result b
|
||||
-- ^ Compute the result with the un-discarded results.
|
||||
}
|
||||
```
|
||||
|
||||
If you use the predicate helper functions to construct a predicate, you do not
|
||||
need to change anything (and should get a nice reduction in your resident memory
|
||||
usage). If you supply a function directly, you can recover the old behaviour
|
||||
like so:
|
||||
|
||||
```haskell
|
||||
old :: ([(Either Failure a, Trace)] -> Result a) -> ProPredicate a a
|
||||
old p = ProPredicate
|
||||
{ pdiscard = const Nothing
|
||||
, peval = p
|
||||
}
|
||||
```
|
||||
|
||||
The `alwaysTrue2` helper function is gone. If you use it, use `alwaysSameOn` or
|
||||
`alwaysSameBy` instead.
|
||||
|
||||
|
||||
Need help?
|
||||
----------
|
||||
|
||||
- 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][].
|
||||
|
||||
[dejafu-1.0.0.0]: https://hackage.haskell.org/package/dejafu-1.0.0.0
|
||||
[dejafu-0.x]: https://hackage.haskell.org/package/dejafu-0.9.1.1
|
||||
[concurrency-1.3.0.0]: https://hackage.haskell.org/package/concurrency-1.3.0.0
|
||||
[dejafu]: https://hackage.haskell.org/package/dejafu
|
||||
[hunit-dejafu]: https://hackage.haskell.org/package/hunit-dejafu
|
||||
[tasty-dejafu]: https://hackage.haskell.org/package/tasty-dejafu
|
||||
[HUnit]: https://hackage.haskell.org/package/HUnit
|
||||
[file an issue]: https://github.com/barrucadu/dejafu/issues/
|
||||
117
docs/src/migration-guides/1x-2x.md
Normal file
117
docs/src/migration-guides/1x-2x.md
Normal file
@ -0,0 +1,117 @@
|
||||
1.x to 2.x
|
||||
==========
|
||||
|
||||
[dejafu-2.0.0.0][] is a super-major release which breaks compatibility with
|
||||
[dejafu-1.x][].
|
||||
|
||||
Highlights reel:
|
||||
|
||||
- Test cases are written in terms of a new `Program` type.
|
||||
- The `Failure` type has been replaced with a `Condition` type (actually in
|
||||
1.12).
|
||||
- Random testing takes an optional length bound.
|
||||
- Atomically-checked invariants over shared mutable state.
|
||||
|
||||
See the changelogs for the full details.
|
||||
|
||||
|
||||
The `Program` type
|
||||
------------------
|
||||
|
||||
The `ConcT` type is now an alias for `Program Basic`.
|
||||
|
||||
A `Program Basic` has all the instances `ConcT` did, defined using the `~`
|
||||
instance trick, so this shouldn't be a breaking change:
|
||||
|
||||
```haskell
|
||||
instance (pty ~ Basic) => MonadTrans (Program pty)
|
||||
instance (pty ~ Basic) => MonadCatch (Program pty n)
|
||||
instance (pty ~ Basic) => MonadThrow (Program pty n)
|
||||
instance (pty ~ Basic) => MonadMask (Program pty n)
|
||||
instance (pty ~ Basic, Monad n) => MonadConc (Program pty n)
|
||||
instance (pty ~ Basic, MonadIO n) => MonadIO (Program pty n)
|
||||
```
|
||||
|
||||
The `dontCheck` function has been removed in favour of `withSetup`:
|
||||
|
||||
```haskell
|
||||
do x <- dontCheck setup
|
||||
action x
|
||||
|
||||
-- becomes
|
||||
|
||||
withSetup setup action
|
||||
```
|
||||
|
||||
The `subconcurrency` function has been removed in favour of
|
||||
`withSetupAndTeardown`:
|
||||
|
||||
```haskell
|
||||
do x <- setup
|
||||
y <- subconcurrency (action x)
|
||||
teardown x y
|
||||
|
||||
-- becomes
|
||||
|
||||
withSetupAndTeardown setup teardown action
|
||||
```
|
||||
|
||||
The `dontCheck` and `subconcurrency` functions used to throw runtime errors if
|
||||
nested. This is not possible with `withSetup` and `withSetupAndTeardown` due to
|
||||
their types:
|
||||
|
||||
```haskell
|
||||
withSetup
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Program Basic n a)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetup x) n a
|
||||
|
||||
withSetupAndTeardown
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Either Condition y -> Program Basic n a)
|
||||
-- ^ Teardown action
|
||||
-> (x -> Program Basic n y)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetupAndTeardown x y) n a
|
||||
```
|
||||
|
||||
Previously, multiple calls to `subconcurrency` could be sequenced in the same
|
||||
test case. This is not possible using `withSetupAndTeardown`. If you rely on
|
||||
this behaviour, please [file an issue][].
|
||||
|
||||
|
||||
The `Condition` type
|
||||
--------------------
|
||||
|
||||
This is a change in [dejafu-1.12.0.0][dejafu-1.x], but the alias `Failure =
|
||||
Condition` is removed in [dejafu-2.0.0.0][].
|
||||
|
||||
- The `STMDeadlock` and `Deadlock` constructors have been merged.
|
||||
- Internal errors have been split into the `Error` type and are raised as
|
||||
exceptions, instead of being returned as conditions.
|
||||
|
||||
The name "failure" has been a recurring source of confusion, because an
|
||||
individual execution can "fail" without the predicate as a whole failing. My
|
||||
hope is that the more neutral "condition" will prevent this confusion.
|
||||
|
||||
|
||||
Deprecated functions
|
||||
--------------------
|
||||
|
||||
All the deprecated special-purpose functions have been removed. Use more
|
||||
general `*WithSettings` functions instead.
|
||||
|
||||
|
||||
Need help?
|
||||
----------
|
||||
|
||||
- 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][].
|
||||
|
||||
[dejafu-2.0.0.0]: https://hackage.haskell.org/package/dejafu-2.0.0.0
|
||||
[dejafu-1.x]: https://hackage.haskell.org/package/dejafu-1.12.0.0
|
||||
[file an issue]: https://github.com/barrucadu/dejafu/issues/
|
||||
148
docs/src/refinement-testing.md
Normal file
148
docs/src/refinement-testing.md
Normal file
@ -0,0 +1,148 @@
|
||||
Refinement Testing
|
||||
==================
|
||||
|
||||
Déjà Fu also supports a form of property-testing where you can check things
|
||||
about the side-effects of stateful operations. For example, we can assert that
|
||||
`readMVar` is equivalent to sequencing `takeMVar` and `putMVar` like so:
|
||||
|
||||
```haskell
|
||||
prop_mvar_read_take_put =
|
||||
sig readMVar `equivalentTo` sig (\v -> takeMVar v >>= putMVar v)
|
||||
```
|
||||
|
||||
Given the signature function, `sig`, defined in the next section. If we check
|
||||
this, our property fails!
|
||||
|
||||
```text
|
||||
> check prop_mvar_read_take_put
|
||||
*** Failure: (seed Just 0)
|
||||
left: [(Nothing,Just 0)]
|
||||
right: [(Nothing,Just 0),(Just Deadlock,Just 0)]
|
||||
False
|
||||
```
|
||||
|
||||
This is because `readMVar` is atomic, whereas sequencing `takeMVar` with
|
||||
`putMVar` is not, and so another thread can interfere with the `MVar` in the
|
||||
middle. The `check` and `equivalentTo` functions come from
|
||||
`Test.DejaFu.Refinement` (also re-exported from `Test.DejaFu`).
|
||||
|
||||
|
||||
Signatures
|
||||
----------
|
||||
|
||||
A signature tells the property-tester something about the state your operation
|
||||
acts upon, it has a few components:
|
||||
|
||||
```haskell
|
||||
data Sig s o x = Sig
|
||||
{ initialise :: x -> ConcIO s
|
||||
, observe :: s -> x -> ConcIO o
|
||||
, interfere :: s -> x -> ConcIO ()
|
||||
, expression :: s -> ConcIO ()
|
||||
}
|
||||
```
|
||||
|
||||
- `s` is the **state type**, it's the thing which your operations mutate. For
|
||||
`readMVar`, the state is some `MVar a`.
|
||||
|
||||
- `o` is the **observation type**, it's some pure (and comparable) proxy for a
|
||||
snapshot of your mutable state. For `MVar a`, the observation is probably a
|
||||
`Maybe a`.
|
||||
|
||||
- `x` is the **seed type**, it's some pure value used to construct the initial
|
||||
mutable state. For `MVar a`, the seed is probably a `Maybe a`.
|
||||
|
||||
- `ConcIO` is just one of the instances of `MonadConc` that Déjà Fu defines for
|
||||
testing purposes. Just write code polymorphic in the monad as usual, and all
|
||||
will work.
|
||||
|
||||
The `initialise`, `observe`, and `expression` functions should be
|
||||
self-explanatory, but the `interfere` one may not be. It's the job of the
|
||||
`interfere` function to change the state in some way; it's run concurrently with
|
||||
the expression, to simulate the nondeterministic action of other threads.
|
||||
|
||||
Here's a concrete example for our `MVar` example:
|
||||
|
||||
```haskell
|
||||
sig :: (MVar ConcIO Int -> ConcIO a) -> Sig (MVar ConcIO Int) (Maybe Int) (Maybe Int)
|
||||
sig e = Sig
|
||||
{ initialise = maybe newEmptyMVar newMVar
|
||||
, observe = \v _ -> tryTakeMVar v
|
||||
, interfere = \v s -> tryTakeMVar v >> maybe (pure ()) (\x -> void $ tryPutMVar v (x * 1000)) s
|
||||
, expression = void . e
|
||||
}
|
||||
```
|
||||
|
||||
The `observe` function should be deterministic, but as it is run after the
|
||||
normal execution ends, it may have side-effects on the state. The `interfere`
|
||||
function can do just about anything (there are probably some concrete rules for
|
||||
a good function, but I haven't figured them out yet), but a poor one may result
|
||||
in the property-checker being unable to distinguish between atomic and nonatomic
|
||||
expressions.
|
||||
|
||||
|
||||
Properties
|
||||
----------
|
||||
|
||||
A property is a pair of signatures linked by one of three provided
|
||||
functions. These functions are:
|
||||
|
||||
| Function | Operator | Checks that... |
|
||||
| - | - | - |
|
||||
| `equivalentTo` | `===` | ... the left and right have exactly the same behaviours |
|
||||
| `refines` | `=>=` | ... every behaviour of the left is also a behaviour of the right |
|
||||
| `strictlyRefines` | `->-` | ... `left =>= right` holds but `left === right` does not |
|
||||
|
||||
The signatures can have different state types, as long as the seed and
|
||||
observation types are the same. This lets you compare different implementations
|
||||
of the same idea: for example, comparing a concurrent stack implemented using
|
||||
`MVar` with one implemented using `IORef`.
|
||||
|
||||
Properties can have parameters, given in the obvious way:
|
||||
|
||||
```haskell
|
||||
check $ \a b c -> sig1 ... `op` sig2 ...
|
||||
```
|
||||
|
||||
Under the hood, seed and parameter values are generated using the [leancheck][]
|
||||
package, an enumerative property-based testing library. This means that any
|
||||
types you use will need to have a `Listable` instance.
|
||||
|
||||
You can also think about the three functions in terms of sets of results, where
|
||||
a result is a `(Maybe Failure, o)` value. A `Failure` is something like
|
||||
deadlocking, or being killed by an exception; `o` is the observation type. An
|
||||
observation is always made, even if execution of the expression fails.
|
||||
|
||||
| Function | Result-set operation |
|
||||
| - | - |
|
||||
| `refines` | For all seed and parameter assignments, subset-or-equal |
|
||||
| `strictlyRefines` | For at least one seed and parameter assignment, proper subset; for all others, subset-or-equal |
|
||||
| `equivalentTo` | For all seed and parameter assignments, equality |
|
||||
|
||||
Finally, there is an `expectFailure` function, which inverts the expected result
|
||||
of a property.
|
||||
|
||||
The Déjà Fu testsuite has [a collection of refinement properties][], which may
|
||||
help you get a feel for this sort of testing.
|
||||
|
||||
[leancheck]: https://hackage.haskell.org/package/leancheck
|
||||
[a collection of refinement properties]: https://github.com/barrucadu/dejafu/blob/2a15549d97c2fa12f5e8b92ab918fdb34da78281/dejafu-tests/Cases/Refinement.hs
|
||||
|
||||
|
||||
Using HUnit and Tasty
|
||||
---------------------
|
||||
|
||||
As for unit testing, [HUnit][] and [tasty][] integration is provided for
|
||||
refinement testing in the [hunit-dejafu][] and [tasty-dejafu][] packages.
|
||||
|
||||
The `testProperty` function is used to check properties. Our example from the
|
||||
start becomes:
|
||||
|
||||
```haskell
|
||||
testProperty "Read is equivalent to Take then Put" prop_mvar_read_take_put
|
||||
```
|
||||
|
||||
[HUnit]: https://hackage.haskell.org/package/HUnit
|
||||
[tasty]: https://hackage.haskell.org/package/tasty
|
||||
[hunit-dejafu]: https://hackage.haskell.org/package/hunit-dejafu
|
||||
[tasty-dejafu]: https://hackage.haskell.org/package/tasty-dejafu
|
||||
115
docs/src/typeclasses.md
Normal file
115
docs/src/typeclasses.md
Normal file
@ -0,0 +1,115 @@
|
||||
Typeclasses
|
||||
===========
|
||||
|
||||
We don't use the regular `Control.Concurrent` and `Control.Exception` modules,
|
||||
we use typeclass-generalised ones instead from the [concurrency][h:conc] and
|
||||
[exceptions][h:exc] packages.
|
||||
|
||||
[h:conc]: https://hackage.haskell.org/package/concurrency
|
||||
[h:exc]: https://hackage.haskell.org/package/exceptions
|
||||
|
||||
|
||||
Porting guide
|
||||
-------------
|
||||
|
||||
If you want to test some existing code, you'll need to port it to the
|
||||
appropriate typeclass. The typeclass is necessary, because we can't peek inside
|
||||
`IO` and `STM` values, so we need to able to plug in an alternative
|
||||
implementation when testing.
|
||||
|
||||
Fortunately, this tends to be a fairly mechanical and type-driven process:
|
||||
|
||||
1. Import `Control.Concurrent.Classy.*` instead of `Control.Concurrent.*`
|
||||
|
||||
2. Import `Control.Monad.Catch` instead of `Control.Exception`
|
||||
|
||||
3. Change your monad type:
|
||||
|
||||
- `IO a` becomes `MonadConc m => m a`
|
||||
- `STM a` becomes `MonadSTM stm => stm a`
|
||||
|
||||
4. Parameterise your state types by the monad:
|
||||
|
||||
- `TVar` becomes `TVar stm`
|
||||
- `MVar` becomes `MVar m`
|
||||
- `IORef` becomes `IORef m`
|
||||
|
||||
5. Some functions are renamed:
|
||||
|
||||
- `forkIO*` becomes `fork*`
|
||||
- `atomicModifyIORefCAS` becomes `modifyIORefCAS*`
|
||||
|
||||
6. Fix the type errors
|
||||
|
||||
If you're lucky enough to be starting a new concurrent Haskell project, you can
|
||||
just program against the `MonadConc` interface.
|
||||
|
||||
|
||||
What if I really need I/O?
|
||||
--------------------------
|
||||
|
||||
You can use `MonadIO` and `liftIO` with `MonadConc`, for instance if you need to
|
||||
talk to a database (or just use some existing library which needs real I/O).
|
||||
|
||||
To test `IO`-using code, there are some rules you need to follow:
|
||||
|
||||
1. Given the same set of scheduling decisions, your `IO` code must be
|
||||
deterministic (see below).
|
||||
|
||||
2. As dejafu can't inspect `IO` values, they should be kept small; otherwise
|
||||
dejafu may miss buggy interleavings.
|
||||
|
||||
3. You absolutely cannot block on the action of another thread inside `IO`, or
|
||||
the test execution will just deadlock.
|
||||
|
||||
```admonish tip
|
||||
Deterministic `IO` is only essential if you're using the systematic testing (the
|
||||
default). Nondeterministic `IO` won't break the random testing, it'll just make
|
||||
things more confusing.
|
||||
```
|
||||
|
||||
|
||||
Deriving your own instances
|
||||
---------------------------
|
||||
|
||||
There are `MonadConc` and `MonadSTM` instances for many common monad
|
||||
transformers. In the simple case, where you want an instance for a newtype
|
||||
wrapper around a type that has an instance, you may be able to derive it. For
|
||||
example:
|
||||
|
||||
```haskell
|
||||
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
|
||||
{-# LANGUAGE StandaloneDeriving #-}
|
||||
{-# LANGUAGE UndecidableInstances #-}
|
||||
|
||||
data Env = Env
|
||||
|
||||
newtype MyMonad m a = MyMonad { runMyMonad :: ReaderT Env m a }
|
||||
deriving (Functor, Applicative, Monad)
|
||||
|
||||
deriving instance MonadThrow m => MonadThrow (MyMonad m)
|
||||
deriving instance MonadCatch m => MonadCatch (MyMonad m)
|
||||
deriving instance MonadMask m => MonadMask (MyMonad m)
|
||||
|
||||
deriving instance MonadConc m => MonadConc (MyMonad m)
|
||||
```
|
||||
|
||||
`MonadSTM` needs a slightly different set of classes:
|
||||
|
||||
```haskell
|
||||
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
|
||||
{-# LANGUAGE StandaloneDeriving #-}
|
||||
{-# LANGUAGE UndecidableInstances #-}
|
||||
|
||||
data Env = Env
|
||||
|
||||
newtype MyMonad m a = MyMonad { runMyMonad :: ReaderT Env m a }
|
||||
deriving (Functor, Applicative, Monad, Alternative, MonadPlus)
|
||||
|
||||
deriving instance MonadThrow m => MonadThrow (MyMonad m)
|
||||
deriving instance MonadCatch m => MonadCatch (MyMonad m)
|
||||
|
||||
deriving instance MonadSTM m => MonadSTM (MyMonad m)
|
||||
```
|
||||
|
||||
Don't be put off by the use of `UndecidableInstances`, it's safe here.
|
||||
240
docs/src/unit-testing.md
Normal file
240
docs/src/unit-testing.md
Normal file
@ -0,0 +1,240 @@
|
||||
Unit Testing
|
||||
============
|
||||
|
||||
Writing tests with Déjà Fu is a little different to traditional unit testing, as
|
||||
your test case may have multiple results. A "test" is a combination of your
|
||||
code, and a predicate which says something about the set of allowed results.
|
||||
|
||||
Most tests will look something like this:
|
||||
|
||||
```haskell
|
||||
dejafu "Assert the thing holds" myPredicate myAction
|
||||
```
|
||||
|
||||
The `dejafu` function comes from `Test.DejaFu`. Another useful function is
|
||||
`dejafuWithSettings` (see [Advanced Usage](./advanced-usage.md)).
|
||||
|
||||
|
||||
Actions
|
||||
-------
|
||||
|
||||
An action is just something with the type `MonadConc m => m a`, or `(MonadConc
|
||||
m, MonadIO m) => m a` for some `a` that your chosen predicate can deal with.
|
||||
|
||||
For example, some users on Reddit found a couple of apparent bugs in the
|
||||
[auto-update][h:auto] package a while ago ([thread here][auto-thread]). As the
|
||||
package is simple and self-contained, I translated it to the `MonadConc`
|
||||
abstraction and wrote a couple of tests to replicate the bugs. Here they are:
|
||||
|
||||
```haskell
|
||||
deadlocks :: MonadConc m => m ()
|
||||
deadlocks = do
|
||||
auto <- mkAutoUpdate defaultUpdateSettings
|
||||
auto
|
||||
|
||||
nondeterministic :: forall m. MonadConc m => m Int
|
||||
nondeterministic = do
|
||||
var <- newIORef 0
|
||||
let settings = (defaultUpdateSettings :: UpdateSettings m ())
|
||||
{ updateAction = atomicModifyIORef var (\x -> (x+1, x)) }
|
||||
auto <- mkAutoUpdate settings
|
||||
auto
|
||||
auto
|
||||
```
|
||||
|
||||
These actions action could be tested with `autocheck`, and the issues would be
|
||||
revealed. The use of `ScopedTypeVariables` in the second is an unfortunate
|
||||
example of what can happen when everything becomes more polymorphic. But other
|
||||
than that, note how there is no special mention of Déjà Fu in the actions: it's
|
||||
just normal concurrent Haskell, simply written against a different interface.
|
||||
|
||||
The modified package is included [in the test suite][], if you want to see the
|
||||
full code.
|
||||
|
||||
```admonish note
|
||||
The predicates in dejafu-tests are a little confusing, as they're the opposite
|
||||
of what you would normally write! These predicates are checking that the bug is
|
||||
found, not that the code is correct.
|
||||
```
|
||||
|
||||
If the RTS supports bound threads (the `-threaded` flag was passed to GHC when
|
||||
linking), then the main thread of an action given to Déjà Fu will be bound, and
|
||||
further bound threads can be forked with the `forkOS` functions. If not, then
|
||||
attempting to fork a bound thread will raise an error.
|
||||
|
||||
[h:auto]: https://hackage.haskell.org/package/auto-update
|
||||
[auto-thread]: https://www.reddit.com/r/haskell/comments/2i5d7m/updating_autoupdate/
|
||||
[in the test suite]: https://github.com/barrucadu/dejafu/blob/2a15549d97c2fa12f5e8b92ab918fdb34da78281/dejafu-tests/Examples/AutoUpdate.hs
|
||||
|
||||
|
||||
Conditions
|
||||
----------
|
||||
|
||||
When a concurrent program of type `MonadConc m => m a` is executed, it may
|
||||
produce a value of type `a`, or it may experience a **condition** such as
|
||||
deadlock.
|
||||
|
||||
A condition does not necessarily cause your test to fail. It's important to be
|
||||
aware of what exactly your test is testing, to avoid drawing the wrong
|
||||
conclusions from a passing (or failing) test.
|
||||
|
||||
|
||||
Setup and Teardown
|
||||
------------------
|
||||
|
||||
Because dejafu drives the execution of the program under test, there are some
|
||||
tricks available to you which are not possible using normal concurrent Haskell.
|
||||
|
||||
If your test does some set-up work which is required for your test to work, but
|
||||
which is not the actual thing you are testing, you can define that as a **setup
|
||||
action**:
|
||||
|
||||
```haskell
|
||||
withSetup
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Program Basic n a)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetup x) n a
|
||||
```
|
||||
|
||||
dejafu will save the state at the end of the setup action, and efficiently
|
||||
restore that state in subsequent runs of the same test with a different
|
||||
schedule. This can be much more efficient than dejafu running the setup action
|
||||
normally every single time.
|
||||
|
||||
If you want to examine some state you created in your setup action even if your
|
||||
actual test case deadlocks or something, you can define a **teardown action**:
|
||||
|
||||
```haskell
|
||||
withSetupAndTeardown
|
||||
:: Program Basic n x
|
||||
-- ^ Setup action
|
||||
-> (x -> Either Condition y -> Program Basic n a)
|
||||
-- ^ Teardown action
|
||||
-> (x -> Program Basic n y)
|
||||
-- ^ Main program
|
||||
-> Program (WithSetupAndTeardown x y) n a
|
||||
```
|
||||
|
||||
The teardown action is always executed.
|
||||
|
||||
Finally, if you want to ensure that some invariant holds over some shared state,
|
||||
you can define invariants in the setup action, which are checked atomically
|
||||
during the main action:
|
||||
|
||||
```haskell
|
||||
-- slightly contrived example
|
||||
let setup = do
|
||||
var <- newEmptyMVar
|
||||
registerInvariant $ do
|
||||
value <- inspectMVar var
|
||||
when (x == Just 1) (throwM Overflow)
|
||||
pure var
|
||||
in withSetup setup $ \var -> do
|
||||
fork $ putMVar var 0
|
||||
fork $ putMVar var 1
|
||||
tryReadMVar var
|
||||
```
|
||||
|
||||
If the main action violates the invariant, it is terminated with an
|
||||
`InvariantFailure` condition, and any teardown action is run.
|
||||
|
||||
|
||||
Predicates
|
||||
----------
|
||||
|
||||
There are a few predicates built in, and some helpers to define your own.
|
||||
|
||||
|
||||
| | |
|
||||
| - | - |
|
||||
| `abortsNever` | checks that the computation never aborts |
|
||||
| `abortsAlways` | checks that the computation always aborts |
|
||||
| `abortsSometimes` | checks that the computation aborts at least once |
|
||||
|
||||
An **abort** is where the scheduler chooses to terminate execution early. If
|
||||
you see it, it probably means that a test didn't terminate before it hit the
|
||||
execution length limit. Aborts are hidden unless you use explicitly enable
|
||||
them, see (see [Advanced Usage](./advanced-usage.md)).
|
||||
|
||||
| | |
|
||||
| - | - |
|
||||
| `deadlocksNever` | checks that the computation never deadlocks |
|
||||
| `deadlocksAlways` | checks that the computation always deadlocks |
|
||||
| `deadlocksSometimes` | checks that the computation deadlocks at least once |
|
||||
|
||||
**Deadlocking** is where every thread becomes blocked. This can be, for
|
||||
example, if every thread is trying to read from an `MVar` that has been emptied.
|
||||
|
||||
| | |
|
||||
| - | - |
|
||||
| `exceptionsNever` | checks that the main thread is never killed by an exception |
|
||||
| `exceptionsAlways` | checks that the main thread is always killed by an exception |
|
||||
| `exceptionsSometimes` | checks that the main thread is killed by an exception at least once |
|
||||
|
||||
An uncaught **exception** in the main thread kills the process. These can be
|
||||
synchronous (thrown in the main thread) or asynchronous (thrown to it from a
|
||||
different thread).
|
||||
|
||||
| | |
|
||||
| - | - |
|
||||
| `alwaysSame` | checks that the computation is deterministic and always produces a value |
|
||||
| `alwaysSameOn f` | is like `alwaysSame`, but transforms the results with `f` first |
|
||||
| `alwaysSameBy f` | is like `alwaysSame`, but uses `f` instead of `(==)` to compare |
|
||||
| `notAlwaysSame` | checks that the computation is nondeterministic |
|
||||
| `notAlwaysSameOn f` | is like `notAlwaysSame`, but transforms the results with `f` first |
|
||||
| `notAlwaysSameBy f` | is like `notAlwaysSame`, but uses `f` instead of `(==)` to compare |
|
||||
|
||||
Checking for **determinism** will also find nondeterministic failures:
|
||||
deadlocking (for instance) is still a result of a test!
|
||||
|
||||
| | |
|
||||
| - | - |
|
||||
| `alwaysTrue p` | checks that `p` is true for every result |
|
||||
| `somewhereTrue p` | checks that `p` is true for at least one result |
|
||||
|
||||
These can be used to check custom predicates. For example, you might want all
|
||||
your results to be less than five.
|
||||
|
||||
| | |
|
||||
| - | - |
|
||||
| `gives xs` |checks that the set of results is exactly `xs` (which may include conditions) |
|
||||
| `gives' xs` |checks that the set of results is exactly `xs` (which may not include conditions) |
|
||||
|
||||
These let you say exactly what you want the results to be. Your test will fail
|
||||
if it has any extra results, or misses a result.
|
||||
|
||||
You can check multiple predicates against the same collection of results using
|
||||
the `dejafus` and `dejafusWithSettings` functions. These avoid recomputing the
|
||||
results, and so may be faster than multiple `dejafu` / `dejafuWithSettings`
|
||||
calls.
|
||||
|
||||
|
||||
Using HUnit and Tasty
|
||||
---------------------
|
||||
|
||||
By itself, Déjà Fu has no framework in place for named test groups and parallel
|
||||
execution or anything like that. It does one thing and does it well, which is
|
||||
running test cases for concurrent programs. [HUnit][] and [tasty][] integration
|
||||
is provided to get more of the features you'd expect from a testing framework.
|
||||
|
||||
The integration is provided by the [hunit-dejafu][] and [tasty-dejafu][]
|
||||
packages.
|
||||
|
||||
There's a simple naming convention used: the `Test.DejaFu` function `dejafuFoo`
|
||||
is wrapped in the appropriate way and exposed as `testDejafuFoo` from
|
||||
`Test.HUnit.DejaFu` and `Test.Tasty.DejaFu`.
|
||||
|
||||
Our example from the start becomes:
|
||||
|
||||
```haskell
|
||||
testDejafu "Assert the thing holds" myPredicate myAction
|
||||
```
|
||||
|
||||
The `autocheck` function is exposed as `testAuto`.
|
||||
|
||||
[HUnit]: https://hackage.haskell.org/package/HUnit
|
||||
[tasty]: https://hackage.haskell.org/package/tasty
|
||||
[hunit-dejafu]: https://hackage.haskell.org/package/hunit-dejafu
|
||||
[tasty-dejafu]: https://hackage.haskell.org/package/tasty-dejafu
|
||||
@ -90,43 +90,47 @@ Added
|
||||
~~~~~
|
||||
|
||||
* Re-exports for the ``Program`` types and their constructors:
|
||||
* ``Test.HUnit.DejaFu.Program``
|
||||
* ``Test.HUnit.DejaFu.Basic``
|
||||
* ``Test.HUnit.DejaFu.ConcT``
|
||||
* ``Test.HUnit.DejaFu.ConcIO``
|
||||
* ``Test.HUnit.DejaFu.WithSetup``
|
||||
* ``Test.HUnit.DejaFu.WithSetupAndTeardown``
|
||||
* ``Test.HUnit.DejaFu.withSetup``
|
||||
* ``Test.HUnit.DejaFu.withTeardown``
|
||||
* ``Test.HUnit.DejaFu.withSetupAndTeardown``
|
||||
|
||||
* ``Test.HUnit.DejaFu.Program``
|
||||
* ``Test.HUnit.DejaFu.Basic``
|
||||
* ``Test.HUnit.DejaFu.ConcT``
|
||||
* ``Test.HUnit.DejaFu.ConcIO``
|
||||
* ``Test.HUnit.DejaFu.WithSetup``
|
||||
* ``Test.HUnit.DejaFu.WithSetupAndTeardown``
|
||||
* ``Test.HUnit.DejaFu.withSetup``
|
||||
* ``Test.HUnit.DejaFu.withTeardown``
|
||||
* ``Test.HUnit.DejaFu.withSetupAndTeardown``
|
||||
|
||||
* Re-exports for the ``Invariant`` type and its functions:
|
||||
* ``Test.HUnit.DejaFu.Invariant``
|
||||
* ``Test.HUnit.DejaFu.registerInvariant``
|
||||
* ``Test.HUnit.DejaFu.inspectIORef``
|
||||
* ``Test.HUnit.DejaFu.inspectMVar``
|
||||
* ``Test.HUnit.DejaFu.inspectTVar``
|
||||
|
||||
* ``Test.HUnit.DejaFu.Invariant``
|
||||
* ``Test.HUnit.DejaFu.registerInvariant``
|
||||
* ``Test.HUnit.DejaFu.inspectIORef``
|
||||
* ``Test.HUnit.DejaFu.inspectMVar``
|
||||
* ``Test.HUnit.DejaFu.inspectTVar``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
|
||||
* Functions which took a ``ConcIO`` now take a ``Program pty IO``:
|
||||
* ``Test.HUnit.DejaFu.testAuto``
|
||||
* ``Test.HUnit.DejaFu.testAutoWay``
|
||||
* ``Test.HUnit.DejaFu.testAutoWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafu``
|
||||
* ``Test.HUnit.DejaFu.testDejafuWay``
|
||||
* ``Test.HUnit.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafus``
|
||||
* ``Test.HUnit.DejaFu.testDejafusWay``
|
||||
* ``Test.HUnit.DejaFu.testDejafusWithSettings``
|
||||
|
||||
* ``Test.HUnit.DejaFu.testAuto``
|
||||
* ``Test.HUnit.DejaFu.testAutoWay``
|
||||
* ``Test.HUnit.DejaFu.testAutoWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafu``
|
||||
* ``Test.HUnit.DejaFu.testDejafuWay``
|
||||
* ``Test.HUnit.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafus``
|
||||
* ``Test.HUnit.DejaFu.testDejafusWay``
|
||||
* ``Test.HUnit.DejaFu.testDejafusWithSettings``
|
||||
|
||||
Removed
|
||||
~~~~~~~
|
||||
|
||||
* The deprecated functions:
|
||||
* ``Test.HUnit.DejaFu.testDejafuDiscard``
|
||||
* ``Test.HUnit.DejaFu.testDejafusDiscard``
|
||||
|
||||
* ``Test.HUnit.DejaFu.testDejafuDiscard``
|
||||
* ``Test.HUnit.DejaFu.testDejafusDiscard``
|
||||
|
||||
Miscellaneous
|
||||
~~~~~~~~~~~~~
|
||||
@ -235,9 +239,9 @@ Miscellaneous
|
||||
|
||||
* GHC 7.10 support is dropped. Dependency lower bounds are:
|
||||
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`dejafu`: 1.5
|
||||
* :hackage:`HUnit`: 1.3.1
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`dejafu`: 1.5
|
||||
* :hackage:`HUnit`: 1.3.1
|
||||
|
||||
* The upper bound on :hackage:`dejafu` is 1.6.
|
||||
|
||||
@ -289,9 +293,9 @@ Added
|
||||
|
||||
* (:pull:`238`) Settings-based test functions:
|
||||
|
||||
* ``Test.HUnit.DejaFu.testAutoWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafusWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testAutoWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.HUnit.DejaFu.testDejafusWithSettings``
|
||||
|
||||
* (:pull:`238`) Re-export of ``Test.DejaFu.Settings``.
|
||||
|
||||
|
||||
@ -158,43 +158,47 @@ Added
|
||||
~~~~~
|
||||
|
||||
* Re-exports for the ``Program`` types and their constructors:
|
||||
* ``Test.Tasty.DejaFu.Program``
|
||||
* ``Test.Tasty.DejaFu.Basic``
|
||||
* ``Test.Tasty.DejaFu.ConcT``
|
||||
* ``Test.Tasty.DejaFu.ConcIO``
|
||||
* ``Test.Tasty.DejaFu.WithSetup``
|
||||
* ``Test.Tasty.DejaFu.WithSetupAndTeardown``
|
||||
* ``Test.Tasty.DejaFu.withSetup``
|
||||
* ``Test.Tasty.DejaFu.withTeardown``
|
||||
* ``Test.Tasty.DejaFu.withSetupAndTeardown``
|
||||
|
||||
* ``Test.Tasty.DejaFu.Program``
|
||||
* ``Test.Tasty.DejaFu.Basic``
|
||||
* ``Test.Tasty.DejaFu.ConcT``
|
||||
* ``Test.Tasty.DejaFu.ConcIO``
|
||||
* ``Test.Tasty.DejaFu.WithSetup``
|
||||
* ``Test.Tasty.DejaFu.WithSetupAndTeardown``
|
||||
* ``Test.Tasty.DejaFu.withSetup``
|
||||
* ``Test.Tasty.DejaFu.withTeardown``
|
||||
* ``Test.Tasty.DejaFu.withSetupAndTeardown``
|
||||
|
||||
* Re-exports for the ``Invariant`` type and its functions:
|
||||
* ``Test.Tasty.DejaFu.Invariant``
|
||||
* ``Test.Tasty.DejaFu.registerInvariant``
|
||||
* ``Test.Tasty.DejaFu.inspectIORef``
|
||||
* ``Test.Tasty.DejaFu.inspectMVar``
|
||||
* ``Test.Tasty.DejaFu.inspectTVar``
|
||||
|
||||
* ``Test.Tasty.DejaFu.Invariant``
|
||||
* ``Test.Tasty.DejaFu.registerInvariant``
|
||||
* ``Test.Tasty.DejaFu.inspectIORef``
|
||||
* ``Test.Tasty.DejaFu.inspectMVar``
|
||||
* ``Test.Tasty.DejaFu.inspectTVar``
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
|
||||
* Functions which took a ``ConcIO`` now take a ``Program pty IO``:
|
||||
* ``Test.Tasty.DejaFu.testAuto``
|
||||
* ``Test.Tasty.DejaFu.testAutoWay``
|
||||
* ``Test.Tasty.DejaFu.testAutoWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafu``
|
||||
* ``Test.Tasty.DejaFu.testDejafuWay``
|
||||
* ``Test.Tasty.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafus``
|
||||
* ``Test.Tasty.DejaFu.testDejafusWay``
|
||||
* ``Test.Tasty.DejaFu.testDejafusWithSettings``
|
||||
|
||||
* ``Test.Tasty.DejaFu.testAuto``
|
||||
* ``Test.Tasty.DejaFu.testAutoWay``
|
||||
* ``Test.Tasty.DejaFu.testAutoWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafu``
|
||||
* ``Test.Tasty.DejaFu.testDejafuWay``
|
||||
* ``Test.Tasty.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafus``
|
||||
* ``Test.Tasty.DejaFu.testDejafusWay``
|
||||
* ``Test.Tasty.DejaFu.testDejafusWithSettings``
|
||||
|
||||
Removed
|
||||
~~~~~~~
|
||||
|
||||
* The deprecated functions:
|
||||
* ``Test.Tasty.DejaFu.testDejafuDiscard``
|
||||
* ``Test.Tasty.DejaFu.testDejafusDiscard``
|
||||
|
||||
* ``Test.Tasty.DejaFu.testDejafuDiscard``
|
||||
* ``Test.Tasty.DejaFu.testDejafusDiscard``
|
||||
|
||||
Miscellaneous
|
||||
~~~~~~~~~~~~~
|
||||
@ -327,8 +331,8 @@ Miscellaneous
|
||||
|
||||
* GHC 7.10 support is dropped. Dependency lower bounds are:
|
||||
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`dejafu`: 1.5
|
||||
* :hackage:`base`: 4.9
|
||||
* :hackage:`dejafu`: 1.5
|
||||
|
||||
* The upper bound on :hackage:`dejafu` is 1.6.
|
||||
|
||||
@ -368,9 +372,9 @@ Added
|
||||
|
||||
* (:pull:`238`) Settings-based test functions:
|
||||
|
||||
* ``Test.Tasty.DejaFu.testAutoWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafusWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testAutoWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafuWithSettings``
|
||||
* ``Test.Tasty.DejaFu.testDejafusWithSettings``
|
||||
|
||||
* (:pull:`238`) Re-export of ``Test.DejaFu.Settings``.
|
||||
|
||||
@ -611,8 +615,8 @@ Added
|
||||
* Orphan ``IsOption`` instance for ``Test.DejaFu.SCT.Way``.
|
||||
Command-line parameters are:
|
||||
|
||||
* "systematically": systematic testing with the default bounds
|
||||
* "randomly": 100 executions with a fixed random seed
|
||||
* "systematically": systematic testing with the default bounds
|
||||
* "randomly": 100 executions with a fixed random seed
|
||||
|
||||
Changed
|
||||
~~~~~~~
|
||||
@ -670,9 +674,9 @@ Added
|
||||
* Orphan ``IsOption`` instances for ``Test.DejaFu.SCT.Bounds`` and
|
||||
``MemType``. Command-line parameters are:
|
||||
|
||||
* "sc": sequential consistency
|
||||
* "tso": total store order
|
||||
* "pso": partial store order
|
||||
* "sc": sequential consistency
|
||||
* "tso": total store order
|
||||
* "pso": partial store order
|
||||
|
||||
* Re-export ``Test.DejaFu.SCT.Bounds``.
|
||||
|
||||
@ -687,8 +691,8 @@ Miscellaneous
|
||||
|
||||
* Git: :tag:`tasty-dejafu-0.1.1.0`
|
||||
|
||||
**Note:** this was misnumbered (it should have been 0.2.1.0) *and* was
|
||||
never pushed to Hackage, whoops!
|
||||
**Note:** this was misnumbered (it should have been 0.2.1.0) *and* was never
|
||||
pushed to Hackage, whoops!
|
||||
|
||||
Miscellaneous
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Loading…
Reference in New Issue
Block a user