GHC/Ptr.lhs

   1 \begin{code}
   2 {-# OPTIONS_GHC -fno-implicit-prelude #-}
   3 -----------------------------------------------------------------------------
   4 -- |
   5 -- Module      :  GHC.Ptr
   6 -- Copyright   :  (c) The FFI Task Force, 2000-2002
   7 -- License     :  see libraries/base/LICENSE
   8 --
   9 -- Maintainer  :  ffi@haskell.org
  10 -- Stability   :  internal
  11 -- Portability :  non-portable (GHC Extensions)
  12 --
  13 -- The 'Ptr' and 'FunPtr' types and operations.
  14 --
  15 -----------------------------------------------------------------------------
  16
  17 -- #hide
  18 module GHC.Ptr where
  19
  20 import GHC.Base
  21
  22 ------------------------------------------------------------------------
  23 -- Data pointers.
  24
  25 data Ptr a = Ptr Addr# deriving (Eq, Ord)
  26 -- ^ A value of type @'Ptr' a@ represents a pointer to an object, or an
  27 -- array of objects, which may be marshalled to or from Haskell values
  28 -- of type @a@.
  29 --
  30 -- The type @a@ will often be an instance of class
  31 -- 'Foreign.Storable.Storable' which provides the marshalling operations.
  32 -- However this is not essential, and you can provide your own operations
  33 -- to access the pointer.  For example you might write small foreign
  34 -- functions to get or set the fields of a C @struct@.
  35
  36 -- |The constant 'nullPtr' contains a distinguished value of 'Ptr'
  37 -- that is not associated with a valid memory location.
  38 nullPtr :: Ptr a
  39 nullPtr = Ptr nullAddr#
  40
  41 -- |The 'castPtr' function casts a pointer from one type to another.
  42 castPtr :: Ptr a -> Ptr b
  43 castPtr (Ptr addr) = Ptr addr
  44
  45 -- |Advances the given address by the given offset in bytes.
  46 plusPtr :: Ptr a -> Int -> Ptr b
  47 plusPtr (Ptr addr) (I# d) = Ptr (plusAddr# addr d)
  48
  49 -- |Given an arbitrary address and an alignment constraint,
  50 -- 'alignPtr' yields the next higher address that fulfills the
  51 -- alignment constraint.  An alignment constraint @x@ is fulfilled by
  52 -- any address divisible by @x@.  This operation is idempotent.
  53 alignPtr :: Ptr a -> Int -> Ptr a
  54 alignPtr addr@(Ptr a) (I# i)
  55   = case remAddr# a i of {
  56       0# -> addr;
  57       n -> Ptr (plusAddr# a (i -# n)) }
  58
  59 -- |Computes the offset required to get from the first to the second
  60 -- argument.  We have
  61 --
  62 -- > p2 == p1 `plusPtr` (p2 `minusPtr` p1)
  63 minusPtr :: Ptr a -> Ptr b -> Int
  64 minusPtr (Ptr a1) (Ptr a2) = I# (minusAddr# a1 a2)
  65
  66 ------------------------------------------------------------------------
  67 -- Function pointers for the default calling convention.
  68
  69 data FunPtr a = FunPtr Addr# deriving (Eq, Ord)
  70 -- ^ A value of type @'FunPtr' a@ is a pointer to a function callable
  71 -- from foreign code.  The type @a@ will normally be a /foreign type/,
  72 -- a function type with zero or more arguments where
  73 --
  74 -- * the argument types are /marshallable foreign types/,
  75 --   i.e. 'Char', 'Int', 'Prelude.Double', 'Prelude.Float',
  76 --   'Bool', 'Data.Int.Int8', 'Data.Int.Int16', 'Data.Int.Int32',
  77 --   'Data.Int.Int64', 'Data.Word.Word8', 'Data.Word.Word16',
  78 --   'Data.Word.Word32', 'Data.Word.Word64', @'Ptr' a@, @'FunPtr' a@,
  79 --   @'Foreign.StablePtr.StablePtr' a@ or a renaming of any of these
  80 --   using @newtype@.
  81 --
  82 -- * the return type is either a marshallable foreign type or has the form
  83 --   @'Prelude.IO' t@ where @t@ is a marshallable foreign type or @()@.
  84 --
  85 -- A value of type @'FunPtr' a@ may be a pointer to a foreign function,
  86 -- either returned by another foreign function or imported with a
  87 -- a static address import like
  88 --
  89 -- > foreign import ccall "stdlib.h &free"
  90 -- >   p_free :: FunPtr (Ptr a -> IO ())
  91 --
  92 -- or a pointer to a Haskell function created using a /wrapper/ stub
  93 -- declared to produce a 'FunPtr' of the correct type.  For example:
  94 --
  95 -- > type Compare = Int -> Int -> Bool
  96 -- > foreign import ccall "wrapper"
  97 -- >   mkCompare :: Compare -> IO (FunPtr Compare)
  98 --
  99 -- Calls to wrapper stubs like @mkCompare@ allocate storage, which
 100 -- should be released with 'Foreign.Ptr.freeHaskellFunPtr' when no
 101 -- longer required.
 102 --
 103 -- To convert 'FunPtr' values to corresponding Haskell functions, one
 104 -- can define a /dynamic/ stub for the specific foreign type, e.g.
 105 --
 106 -- > type IntFunction = CInt -> IO ()
 107 -- > foreign import ccall "dynamic"
 108 -- >   mkFun :: FunPtr IntFunction -> IntFunction
 109
 110 -- |The constant 'nullFunPtr' contains a
 111 -- distinguished value of 'FunPtr' that is not
 112 -- associated with a valid memory location.
 113 nullFunPtr :: FunPtr a
 114 nullFunPtr = FunPtr nullAddr#
 115
 116 -- |Casts a 'FunPtr' to a 'FunPtr' of a different type.
 117 castFunPtr :: FunPtr a -> FunPtr b
 118 castFunPtr (FunPtr addr) = FunPtr addr
 119
 120 -- |Casts a 'FunPtr' to a 'Ptr'.
 121 --
 122 -- /Note:/ this is valid only on architectures where data and function
 123 -- pointers range over the same set of addresses, and should only be used
 124 -- for bindings to external libraries whose interface already relies on
 125 -- this assumption.
 126 castFunPtrToPtr :: FunPtr a -> Ptr b
 127 castFunPtrToPtr (FunPtr addr) = Ptr addr
 128
 129 -- |Casts a 'Ptr' to a 'FunPtr'.
 130 --
 131 -- /Note:/ this is valid only on architectures where data and function
 132 -- pointers range over the same set of addresses, and should only be used
 133 -- for bindings to external libraries whose interface already relies on
 134 -- this assumption.
 135 castPtrToFunPtr :: Ptr a -> FunPtr b
 136 castPtrToFunPtr (Ptr addr) = FunPtr addr
 137 \end{code}
 138