Registry of monadic actions supporting rollback actions and delayed actions in the presence of (a-)synchronous exceptions.

This module is heavily inspired by:

• resource-registry
• resourcet

When a piece of mutable state holding system resources is updated, then it is important to guarantee in the presence of (a-)synchronous exceptions that:

1. Allocated resources end up in the state
2. Freed resources are removed from the state

Consider the example program below. We have some mutable State that holds a file handle/descriptor. We want to mutate this state by closing the current handle, and replacing it by a newly opened handle. Using the tools at our disposal in Control.ActionRegistry, we guarantee (1) and (2).

   type State = MVar Handle

   example :: State -> IO ()
   example st =
     modifyWithActionRegistry_
       (takeMVar st)
       (putMVar st)
       $ \reg h -> do
         h' <- withRollback reg
                 (openFile  "file.txt" ReadWriteMode)
                 hClose
         delayedCommit reg (hClose h)
         pure h'
 

What is also nice about this examples is that it is atomic: other threads will not be able to see the updated State until modifyWithActionRegistry_ has exited and the necessary side effects have been performed. Of course, another thread *could* observe that the file.txt was created before modifyWithActionRegistry_ has exited, but the assumption is that the threads in our program are cooperative. It is up to the user to ensure that actions that are performed as part of the state update do not conflict with other actions.

An ActionRegistry is a registry of monadic actions to support working with resources and mutable state in the presence of (a)synchronous exceptions. It works analogously to database transactions: within the "transaction" scope we can perform actions (such as resource allocations and state changes) and we can register delayed (commit) and rollback actions. The delayed actions are all executed at the end if the transaction scope is exited successfully, but if an exception is thrown (sync or async) then the rollback actions are executed instead, and the exception is propagated.

• Rollback actions are executed in the reverse order in which they were registered, which is the natural nesting order when considered as bracketing.
• Delayed actions are executed in the same order in which they are registered.

Actions are monadic computations that (may) produce side effects. Such side effects can include opening or closing a file handle, but also modifying a mutable variable.

We make a distinction between three types of actions:

• An immediate action is performed immediately, as the name suggests.
• A rollback action is an action that is registered in an action registry, and it is performed precisely when the corresponding action registry is aborted. See withRollback for examples.
• A delayed action is an action that is registered in an action registry, and it is performed precisely when the corresponding action registry is committed. See delayedCommit for examples.

Immediate actions are run with asynchronous exceptions masked to guarantee that the rollback action is registered after the immediate action has returned successfully. This means that all the usual masking caveats apply for the immediate acion.

Rollback actions and delayed actions are performed precisely when aborting or committing an action registry respectively (see Action registry). To achieve this, finalisation of the action registry happens in the same masked state as runnning the registered actions. This means all the usual masking caveats apply for the registered actions.