add paragraph about alignment
[haskell-report.git] / report / libs / Foreign-Marshal-Alloc.tex
1 \haddockmoduleheading{Foreign.Marshal.Alloc}
2 \label{module:Foreign.Marshal.Alloc}
3 \haddockbeginheader
4 {\haddockverb\begin{verbatim}
5 module Foreign.Marshal.Alloc (
6 alloca, allocaBytes, malloc, mallocBytes, realloc, reallocBytes,
7 free, finalizerFree
8 ) where\end{verbatim}}
9 \haddockendheader
10
11 The module \haddocktt{Foreign.Marshal.Alloc} provides operations to allocate and
12 deallocate blocks of raw memory (i.e., unstructured chunks of memory
13 outside of the area maintained by the Haskell storage manager). These
14 memory blocks are commonly used to pass compound data structures to
15 foreign functions or to provide space in which compound result values
16 are obtained from foreign functions.
17 \par
18 If any of the allocation functions fails, a value of \haddocktt{nullPtr} is
19 produced. If \haddockid{free} or \haddockid{reallocBytes} is applied to a memory area
20 that has been allocated with \haddockid{alloca} or \haddockid{allocaBytes}, the
21 behaviour is undefined. Any further access to memory areas allocated with
22 \haddockid{alloca} or \haddockid{allocaBytes}, after the computation that was passed to
23 the allocation function has terminated, leads to undefined behaviour. Any
24 further access to the memory area referenced by a pointer passed to
25 \haddockid{realloc}, \haddockid{reallocBytes}, or \haddockid{free} entails undefined
26 behaviour.
27 \par
28 All storage allocated by functions that allocate based on a \emph{size in bytes}
29 must be sufficiently aligned for any of the basic foreign types
30 that fits into the newly allocated storage. All storage allocated by
31 functions that allocate based on a specific type must be sufficiently
32 aligned for that type. Array allocation routines need to obey the same
33 alignment constraints for each array element.
34 \par
35
36 \section{Memory allocation
37 }
38 \subsection{Local allocation
39 }
40 \begin{haddockdesc}
41 \item[\begin{tabular}{@{}l}
42 alloca\ ::\ Storable\ a\ =>\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
43 \end{tabular}]\haddockbegindoc
44 \haddocktt{alloca\ f} executes the computation \haddocktt{f}, passing as argument
45 a pointer to a temporarily allocated block of memory sufficient to
46 hold values of type \haddocktt{a}.
47 \par
48 The memory is freed when \haddocktt{f} terminates (either normally or via an
49 exception), so the pointer passed to \haddocktt{f} must \emph{not} be used after this.
50 \par
51
52 \end{haddockdesc}
53 \begin{haddockdesc}
54 \item[\begin{tabular}{@{}l}
55 allocaBytes\ ::\ Int\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
56 \end{tabular}]\haddockbegindoc
57 \haddocktt{allocaBytes\ n\ f} executes the computation \haddocktt{f}, passing as argument
58 a pointer to a temporarily allocated block of memory of \haddocktt{n} bytes.
59 The block of memory is sufficiently aligned for any of the basic
60 foreign types that fits into a memory block of the allocated size.
61 \par
62 The memory is freed when \haddocktt{f} terminates (either normally or via an
63 exception), so the pointer passed to \haddocktt{f} must \emph{not} be used after this.
64 \par
65
66 \end{haddockdesc}
67 \subsection{Dynamic allocation
68 }
69 \begin{haddockdesc}
70 \item[\begin{tabular}{@{}l}
71 malloc\ ::\ Storable\ a\ =>\ IO\ (Ptr\ a)
72 \end{tabular}]\haddockbegindoc
73 Allocate a block of memory that is sufficient to hold values of type
74 \haddocktt{a}. The size of the area allocated is determined by the \haddockid{sizeOf}
75 method from the instance of \haddockid{Storable} for the appropriate type.
76 \par
77 The memory may be deallocated using \haddockid{free} or \haddockid{finalizerFree} when
78 no longer required.
79 \par
80
81 \end{haddockdesc}
82 \begin{haddockdesc}
83 \item[\begin{tabular}{@{}l}
84 mallocBytes\ ::\ Int\ ->\ IO\ (Ptr\ a)
85 \end{tabular}]\haddockbegindoc
86 Allocate a block of memory of the given number of bytes.
87 The block of memory is sufficiently aligned for any of the basic
88 foreign types that fits into a memory block of the allocated size.
89 \par
90 The memory may be deallocated using \haddockid{free} or \haddockid{finalizerFree} when
91 no longer required.
92 \par
93
94 \end{haddockdesc}
95 \begin{haddockdesc}
96 \item[\begin{tabular}{@{}l}
97 realloc\ ::\ Storable\ b\ =>\ Ptr\ a\ ->\ IO\ (Ptr\ b)
98 \end{tabular}]\haddockbegindoc
99 Resize a memory area that was allocated with \haddockid{malloc} or \haddockid{mallocBytes}
100 to the size needed to store values of type \haddocktt{b}. The returned pointer
101 may refer to an entirely different memory area, but will be suitably
102 aligned to hold values of type \haddocktt{b}. The contents of the referenced
103 memory area will be the same as of the original pointer up to the
104 minimum of the original size and the size of values of type \haddocktt{b}.
105 \par
106 If the argument to \haddockid{realloc} is \haddockid{nullPtr}, \haddockid{realloc} behaves like
107 \haddockid{malloc}.
108 \par
109
110 \end{haddockdesc}
111 \begin{haddockdesc}
112 \item[\begin{tabular}{@{}l}
113 reallocBytes\ ::\ Ptr\ a\ ->\ Int\ ->\ IO\ (Ptr\ a)
114 \end{tabular}]\haddockbegindoc
115 Resize a memory area that was allocated with \haddockid{malloc} or \haddockid{mallocBytes}
116 to the given size. The returned pointer may refer to an entirely
117 different memory area, but will be sufficiently aligned for any of the
118 basic foreign types that fits into a memory block of the given size.
119 The contents of the referenced memory area will be the same as of
120 the original pointer up to the minimum of the original size and the
121 given size.
122 \par
123 If the pointer argument to \haddockid{reallocBytes} is \haddockid{nullPtr}, \haddockid{reallocBytes}
124 behaves like \haddockid{malloc}. If the requested size is 0, \haddockid{reallocBytes}
125 behaves like \haddockid{free}.
126 \par
127
128 \end{haddockdesc}
129 \begin{haddockdesc}
130 \item[\begin{tabular}{@{}l}
131 free\ ::\ Ptr\ a\ ->\ IO\ ()
132 \end{tabular}]\haddockbegindoc
133 Free a block of memory that was allocated with \haddockid{malloc},
134 \haddockid{mallocBytes}, \haddockid{realloc}, \haddockid{reallocBytes}, \haddocktt{Foreign.Marshal.Utils.new}
135 or any of the \haddocktt{new}\emph{X} functions in \haddocktt{Foreign.Marshal.Array} or
136 \haddocktt{Foreign.C.String}.
137 \par
138
139 \end{haddockdesc}
140 \begin{haddockdesc}
141 \item[\begin{tabular}{@{}l}
142 finalizerFree\ ::\ FinalizerPtr\ a
143 \end{tabular}]\haddockbegindoc
144 A pointer to a foreign function equivalent to \haddockid{free}, which may be
145 used as a finalizer (cf \haddocktt{Foreign.ForeignPtr.ForeignPtr}) for storage
146 allocated with \haddockid{malloc}, \haddockid{mallocBytes}, \haddockid{realloc} or \haddockid{reallocBytes}.
147 \par
148
149 \end{haddockdesc}