Foreign/Concurrent.hs

   1 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
   2 -----------------------------------------------------------------------------
   3 -- |
   4 -- Module      :  Foreign.Concurrent
   5 -- Copyright   :  (c) The University of Glasgow 2003
   6 -- License     :  BSD-style (see the file libraries/base/LICENSE)
   7 --
   8 -- Maintainer  :  ffi@haskell.org
   9 -- Stability   :  provisional
  10 -- Portability :  non-portable (requires concurrency)
  11 --
  12 -- FFI datatypes and operations that use or require concurrency (GHC only).
  13 --
  14 -----------------------------------------------------------------------------
  15
  16 module Foreign.Concurrent
  17   (
  18         -- * Concurrency-based 'ForeignPtr' operations
  19
  20         -- | These functions generalize their namesakes in the portable
  21         -- "Foreign.ForeignPtr" module by allowing arbitrary 'IO' actions
  22         -- as finalizers.  These finalizers necessarily run in a separate
  23         -- thread, cf. /Destructors, Finalizers and Synchronization/,
  24         -- by Hans Boehm, /POPL/, 2003.
  25
  26         newForeignPtr,
  27         addForeignPtrFinalizer,
  28   ) where
  29
  30 #ifdef __GLASGOW_HASKELL__
  31 import GHC.IOBase       ( IO )
  32 import GHC.Ptr          ( Ptr )
  33 import GHC.ForeignPtr   ( ForeignPtr )
  34 import qualified GHC.ForeignPtr
  35 #endif
  36
  37 #ifdef __GLASGOW_HASKELL__
  38 newForeignPtr :: Ptr a -> IO () -> IO (ForeignPtr a)
  39 -- ^Turns a plain memory reference into a foreign object by associating
  40 -- a finalizer - given by the monadic operation - with the reference.
  41 -- The finalizer will be executed after the last reference to the
  42 -- foreign object is dropped.  Note that there is no guarantee on how
  43 -- soon the finalizer is executed after the last reference was dropped;
  44 -- this depends on the details of the Haskell storage manager.  The only
  45 -- guarantee is that the finalizer runs before the program terminates.
  46 newForeignPtr = GHC.ForeignPtr.newConcForeignPtr
  47
  48 addForeignPtrFinalizer :: ForeignPtr a -> IO () -> IO ()
  49 -- ^This function adds a finalizer to the given 'ForeignPtr'.
  50 -- The finalizer will run after the last reference to the foreign object
  51 -- is dropped, but /before/ all previously registered finalizers for the
  52 -- same object.
  53 addForeignPtrFinalizer = GHC.ForeignPtr.addForeignPtrConcFinalizer
  54 #endif