A variant of
throw that can only be used within the
STM
monad.
Throwing an exception in
STM aborts the transaction and
propagates the exception. If the exception is caught via
catchSTM, only the changes enclosed by the catch are rolled
back; changes made outside of
catchSTM persist.
If the exception is not caught inside of the
STM, it is
re-thrown by
atomically, and the entire
STM is rolled
back.
Although
throwSTM has a type that is an instance of the type of
throw, the two functions are subtly different:
throw e `seq` x ===> throw e
throwSTM e `seq` x ===> x
The first example will cause the exception
e to be raised,
whereas the second one won't. In fact,
throwSTM will only cause
an exception to be raised when it is used within the
STM monad.
The
throwSTM variant should be used in preference to
throw to raise an exception within the
STM monad because
it guarantees ordering with respect to other
STM operations,
whereas
throw does not.