castForeignPtr,
newConcForeignPtr,
addForeignPtrConcFinalizer,
+ finalizeForeignPtr
) where
import Control.Monad ( sequence_ )
-- is an arbitrary @IO@ action. When it is invoked, the finalizer
-- will run in a new thread.
--
+-- NB. Be very careful with these finalizers. One common trap is that
+-- if a finalizer references another finalized value, it does not
+-- prevent that value from being finalized. In particular, 'Handle's
+-- are finalized objects, so a finalizer should not refer to a 'Handle'
+-- (including @stdout@, @stdin@ or @stderr@).
+--
addForeignPtrConcFinalizer f@(ForeignPtr fo r) finalizer = do
fs <- readIORef r
writeIORef r (finalizer : fs)
-- ^This function extracts the pointer component of a foreign
-- pointer. This is a potentially dangerous operations, as if the
-- argument to 'unsafeForeignPtrToPtr' is the last usage
--- occurence of the given foreign pointer, then its finaliser(s) will
+-- occurrence of the given foreign pointer, then its finaliser(s) will
-- be run, which potentially invalidates the plain pointer just
-- obtained. Hence, 'touchForeignPtr' must be used
-- wherever it has to be guaranteed that the pointer lives on - i.e.,
-- ^This function casts a 'ForeignPtr'
-- parameterised by one type into another type.
castForeignPtr f = unsafeCoerce# f
+
+-- | Causes a the finalizers associated with a foreign pointer to be run
+-- immediately.
+finalizeForeignPtr :: ForeignPtr a -> IO ()
+finalizeForeignPtr foreignPtr = do
+ finalizers <- readIORef refFinalizers
+ sequence_ finalizers
+ writeIORef refFinalizers []
+ where
+ refFinalizers = case foreignPtr of
+ (ForeignPtr _ ref) -> ref
+ (MallocPtr _ ref) -> ref