-modifyIORef :: IORef a -> (a -> a) -> IO ()
-modifyIORef ref f = writeIORef ref . f =<< readIORef ref
+-- |Atomically modifies the contents of an 'IORef'.
+--
+-- This function is useful for using 'IORef' in a safe way in a multithreaded
+-- program. If you only have one 'IORef', then using 'atomicModifyIORef' to
+-- access and modify it will prevent race conditions.
+--
+-- Extending the atomicity to multiple 'IORef's is problematic, so it
+-- is recommended that if you need to do anything more complicated
+-- then using 'Control.Concurrent.MVar.MVar' instead is a good idea.
+--
+atomicModifyIORef :: IORef a -> (a -> (a,b)) -> IO b
+#if defined(__GLASGOW_HASKELL__)
+atomicModifyIORef = GHC.IORef.atomicModifyIORef