base: Manually unlit .lhs into .hs modules
[ghc.git] / libraries / base / GHC / Ptr.hs
1 {-# LANGUAGE Unsafe #-}
2 {-# LANGUAGE CPP, NoImplicitPrelude, MagicHash, RoleAnnotations #-}
3 {-# OPTIONS_HADDOCK hide #-}
4
5 -----------------------------------------------------------------------------
6 -- |
7 -- Module : GHC.Ptr
8 -- Copyright : (c) The FFI Task Force, 2000-2002
9 -- License : see libraries/base/LICENSE
10 --
11 -- Maintainer : ffi@haskell.org
12 -- Stability : internal
13 -- Portability : non-portable (GHC Extensions)
14 --
15 -- The 'Ptr' and 'FunPtr' types and operations.
16 --
17 -----------------------------------------------------------------------------
18
19 module GHC.Ptr (
20 Ptr(..), FunPtr(..),
21 nullPtr, castPtr, plusPtr, alignPtr, minusPtr,
22 nullFunPtr, castFunPtr,
23
24 -- * Unsafe functions
25 castFunPtrToPtr, castPtrToFunPtr
26 ) where
27
28 import GHC.Base
29 import GHC.Show
30 import GHC.Num
31 import GHC.List ( length, replicate )
32 import Numeric ( showHex )
33
34 #include "MachDeps.h"
35
36 ------------------------------------------------------------------------
37 -- Data pointers.
38
39 -- The role of Ptr's parameter is phantom, as there is no relation between
40 -- the Haskell representation and whathever the user puts at the end of the
41 -- pointer. And phantom is useful to implement castPtr (see #9163)
42
43 -- redundant role annotation checks that this doesn't change
44 type role Ptr phantom
45 data Ptr a = Ptr Addr# deriving (Eq, Ord)
46 -- ^ A value of type @'Ptr' a@ represents a pointer to an object, or an
47 -- array of objects, which may be marshalled to or from Haskell values
48 -- of type @a@.
49 --
50 -- The type @a@ will often be an instance of class
51 -- 'Foreign.Storable.Storable' which provides the marshalling operations.
52 -- However this is not essential, and you can provide your own operations
53 -- to access the pointer. For example you might write small foreign
54 -- functions to get or set the fields of a C @struct@.
55
56 -- |The constant 'nullPtr' contains a distinguished value of 'Ptr'
57 -- that is not associated with a valid memory location.
58 nullPtr :: Ptr a
59 nullPtr = Ptr nullAddr#
60
61 -- |The 'castPtr' function casts a pointer from one type to another.
62 castPtr :: Ptr a -> Ptr b
63 castPtr = coerce
64
65 -- |Advances the given address by the given offset in bytes.
66 plusPtr :: Ptr a -> Int -> Ptr b
67 plusPtr (Ptr addr) (I# d) = Ptr (plusAddr# addr d)
68
69 -- |Given an arbitrary address and an alignment constraint,
70 -- 'alignPtr' yields the next higher address that fulfills the
71 -- alignment constraint. An alignment constraint @x@ is fulfilled by
72 -- any address divisible by @x@. This operation is idempotent.
73 alignPtr :: Ptr a -> Int -> Ptr a
74 alignPtr addr@(Ptr a) (I# i)
75 = case remAddr# a i of {
76 0# -> addr;
77 n -> Ptr (plusAddr# a (i -# n)) }
78
79 -- |Computes the offset required to get from the second to the first
80 -- argument. We have
81 --
82 -- > p2 == p1 `plusPtr` (p2 `minusPtr` p1)
83 minusPtr :: Ptr a -> Ptr b -> Int
84 minusPtr (Ptr a1) (Ptr a2) = I# (minusAddr# a1 a2)
85
86 ------------------------------------------------------------------------
87 -- Function pointers for the default calling convention.
88
89 -- 'FunPtr' has a phantom role for similar reasons to 'Ptr'. Note
90 -- that 'FunPtr's role cannot become nominal without changes elsewhere
91 -- in GHC. See Note [FFI type roles] in TcForeign.
92 type role FunPtr phantom
93 data FunPtr a = FunPtr Addr# deriving (Eq, Ord)
94 -- ^ A value of type @'FunPtr' a@ is a pointer to a function callable
95 -- from foreign code. The type @a@ will normally be a /foreign type/,
96 -- a function type with zero or more arguments where
97 --
98 -- * the argument types are /marshallable foreign types/,
99 -- i.e. 'Char', 'Int', 'Double', 'Float',
100 -- 'Bool', 'Data.Int.Int8', 'Data.Int.Int16', 'Data.Int.Int32',
101 -- 'Data.Int.Int64', 'Data.Word.Word8', 'Data.Word.Word16',
102 -- 'Data.Word.Word32', 'Data.Word.Word64', @'Ptr' a@, @'FunPtr' a@,
103 -- @'Foreign.StablePtr.StablePtr' a@ or a renaming of any of these
104 -- using @newtype@.
105 --
106 -- * the return type is either a marshallable foreign type or has the form
107 -- @'IO' t@ where @t@ is a marshallable foreign type or @()@.
108 --
109 -- A value of type @'FunPtr' a@ may be a pointer to a foreign function,
110 -- either returned by another foreign function or imported with a
111 -- a static address import like
112 --
113 -- > foreign import ccall "stdlib.h &free"
114 -- > p_free :: FunPtr (Ptr a -> IO ())
115 --
116 -- or a pointer to a Haskell function created using a /wrapper/ stub
117 -- declared to produce a 'FunPtr' of the correct type. For example:
118 --
119 -- > type Compare = Int -> Int -> Bool
120 -- > foreign import ccall "wrapper"
121 -- > mkCompare :: Compare -> IO (FunPtr Compare)
122 --
123 -- Calls to wrapper stubs like @mkCompare@ allocate storage, which
124 -- should be released with 'Foreign.Ptr.freeHaskellFunPtr' when no
125 -- longer required.
126 --
127 -- To convert 'FunPtr' values to corresponding Haskell functions, one
128 -- can define a /dynamic/ stub for the specific foreign type, e.g.
129 --
130 -- > type IntFunction = CInt -> IO ()
131 -- > foreign import ccall "dynamic"
132 -- > mkFun :: FunPtr IntFunction -> IntFunction
133
134 -- |The constant 'nullFunPtr' contains a
135 -- distinguished value of 'FunPtr' that is not
136 -- associated with a valid memory location.
137 nullFunPtr :: FunPtr a
138 nullFunPtr = FunPtr nullAddr#
139
140 -- |Casts a 'FunPtr' to a 'FunPtr' of a different type.
141 castFunPtr :: FunPtr a -> FunPtr b
142 castFunPtr = coerce
143
144 -- |Casts a 'FunPtr' to a 'Ptr'.
145 --
146 -- /Note:/ this is valid only on architectures where data and function
147 -- pointers range over the same set of addresses, and should only be used
148 -- for bindings to external libraries whose interface already relies on
149 -- this assumption.
150 castFunPtrToPtr :: FunPtr a -> Ptr b
151 castFunPtrToPtr (FunPtr addr) = Ptr addr
152
153 -- |Casts a 'Ptr' to a 'FunPtr'.
154 --
155 -- /Note:/ this is valid only on architectures where data and function
156 -- pointers range over the same set of addresses, and should only be used
157 -- for bindings to external libraries whose interface already relies on
158 -- this assumption.
159 castPtrToFunPtr :: Ptr a -> FunPtr b
160 castPtrToFunPtr (Ptr addr) = FunPtr addr
161
162
163 ------------------------------------------------------------------------
164 -- Show instances for Ptr and FunPtr
165
166 instance Show (Ptr a) where
167 showsPrec _ (Ptr a) rs = pad_out (showHex (wordToInteger(int2Word#(addr2Int# a))) "")
168 where
169 -- want 0s prefixed to pad it out to a fixed length.
170 pad_out ls =
171 '0':'x':(replicate (2*SIZEOF_HSPTR - length ls) '0') ++ ls ++ rs
172
173 instance Show (FunPtr a) where
174 showsPrec p = showsPrec p . castFunPtrToPtr