Towards https://github.com/ekmett/lens/issues/1090

Ryan Scott authored 3 years ago and Ryan Scott committed 2 years ago

Fixes #82.

See ghc/ghc#16752.

See commercialhaskell/stackage#4444

gelisam authored 7 years ago and Ryan Scott committed 7 years ago

* SomeMSpec

'MSpec' was an existential in 'm', but I want to construct another
type which has both an 'MSpec' and some other 'm'-related fields. So I
am exposing the 'm' in 'MSpec' and creating another existential which
abstracts over it.

* name the MSpecs

I want to reuse them

* a series of tests about detectable effects

To make sure that the all the effects performed while releasing a
resource are preserved, not just the IO effects.

I'm writing the tests first, so the tests currently fail.

* test that the release error wins

It is easy to accidentally implement the 'ExceptT' instance in a way
which causes the error message thrown during 'use' to get propagated
instead of the one thrown by 'release'. When both 'use' and 'release'
throw an IO exception, the one thrown by 'release' wins, so I think we
should follow suit.

* move the CatchT warning to the instance documentation

Now that we have documentation for individual instances, there is no
need to repeat this seldom-used information here.

* explain the difference with lifted-base

The exceptions package used to have an undocumented advantage over
lifted-base, namely that the non-IO effects are not discarded, but
then exceptions-0.9.0 made a breaking change which lost this
advantage. In this PR, I am restoring this advantage, and I am
documenting it, both to help users decide which package to pick, and
so we don't foolishly repeat that mistake.

* change the type of generalBracket, fixes #63

This is the PR's main change. I make the type of 'generalBracket' even
more general, which allows me to fix the implementations of 'StateT'
and 'WriterT' so they don't discard their state changes.

* MonadMask instance for MaybeT

if ExceptT has one, MaybeT should have one too

* onException vs onError

Update the documentation to reflect the difference between an
exception and an error, calling out the cases in which the user might
expect to catch all errors but will only catch all exceptions.

In particular, 'onException' will only run the handler when an
exception is thrown but not when any other kind of error is thrown;
this is not particularly useful, but we can't do better without
changing its type signature. A new function 'onError' is introduced
which does not have this flaw.

* use return instead of pure

to match the style of the existing codebase

* add the changes to the changelog

* add onError to the changelog

* add Show instance for ExitCase

* Explicitly state which constructors of ExitCase correspond to throwE and throwM.

* typos

* next version is 0.10.0

* onError @since 0.10.0

* spell out the difference between onError and onException

* swap the arguments of generalBracket to match bracket

* explain why users probably don't want to call generalBracket directly

* reminder to keep the doc in sync with the implementation

* @since annotations for MaybeT and ExceptT

the Either instance has one, so MaybeT and ExceptT should have one as well

* adjust phrasing

* rename the type variables in bracket*

to match the order in which the actions will be executed, like in
generalBracket.

* import Control.Applicative when required

* use liftM instead of fmap, for older GHCs

* also import Control.Applicative for GHC-7.4

For motivation, see:
https://www.fpcomplete.com/blog/2017/02/monadmask-vs-monadbracket

Michael Snoyman authored 8 years ago and Ryan Scott committed 8 years ago

Came up in a discussion with @bitonic. There's no downside I can see to
the MonadCatch instance. However, the MonadMask instance is a little bit
more controversial, in that it's not actually doing any masking.
However, it's impossible to know that it's not masking the async
exceptions since there are no side-effects from the Either monad.

Of course, by using unsafePerformIO, we could observe the difference,
but I think that's a valid trade-off.

One final argument against MonadMask for Either: it's probably not
terribly useful.