b4fd0fa33aa8e2c703fc6b1ac212de241f001c3c
[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
29 \section{Memory allocation
30 }
31 \subsection{Local allocation
32 }
33 \begin{haddockdesc}
34 \item[\begin{tabular}{@{}l}
35 alloca\ ::\ Storable\ a\ =>\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
36 \end{tabular}]\haddockbegindoc
37 \haddocktt{alloca\ f} executes the computation \haddocktt{f}, passing as argument
38 a pointer to a temporarily allocated block of memory sufficient to
39 hold values of type \haddocktt{a}.
40 \par
41 The memory is freed when \haddocktt{f} terminates (either normally or via an
42 exception), so the pointer passed to \haddocktt{f} must \emph{not} be used after this.
43 \par
44
45 \end{haddockdesc}
46 \begin{haddockdesc}
47 \item[\begin{tabular}{@{}l}
48 allocaBytes\ ::\ Int\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
49 \end{tabular}]\haddockbegindoc
50 \haddocktt{allocaBytes\ n\ f} executes the computation \haddocktt{f}, passing as argument
51 a pointer to a temporarily allocated block of memory of \haddocktt{n} bytes.
52 The block of memory is sufficiently aligned for any of the basic
53 foreign types that fits into a memory block of the allocated size.
54 \par
55 The memory is freed when \haddocktt{f} terminates (either normally or via an
56 exception), so the pointer passed to \haddocktt{f} must \emph{not} be used after this.
57 \par
58
59 \end{haddockdesc}
60 \subsection{Dynamic allocation
61 }
62 \begin{haddockdesc}
63 \item[\begin{tabular}{@{}l}
64 malloc\ ::\ Storable\ a\ =>\ IO\ (Ptr\ a)
65 \end{tabular}]\haddockbegindoc
66 Allocate a block of memory that is sufficient to hold values of type
67 \haddocktt{a}. The size of the area allocated is determined by the \haddockid{sizeOf}
68 method from the instance of \haddockid{Storable} for the appropriate type.
69 \par
70 The memory may be deallocated using \haddockid{free} or \haddockid{finalizerFree} when
71 no longer required.
72 \par
73
74 \end{haddockdesc}
75 \begin{haddockdesc}
76 \item[\begin{tabular}{@{}l}
77 mallocBytes\ ::\ Int\ ->\ IO\ (Ptr\ a)
78 \end{tabular}]\haddockbegindoc
79 Allocate a block of memory of the given number of bytes.
80 The block of memory is sufficiently aligned for any of the basic
81 foreign types that fits into a memory block of the allocated size.
82 \par
83 The memory may be deallocated using \haddockid{free} or \haddockid{finalizerFree} when
84 no longer required.
85 \par
86
87 \end{haddockdesc}
88 \begin{haddockdesc}
89 \item[\begin{tabular}{@{}l}
90 realloc\ ::\ Storable\ b\ =>\ Ptr\ a\ ->\ IO\ (Ptr\ b)
91 \end{tabular}]\haddockbegindoc
92 Resize a memory area that was allocated with \haddockid{malloc} or \haddockid{mallocBytes}
93 to the size needed to store values of type \haddocktt{b}. The returned pointer
94 may refer to an entirely different memory area, but will be suitably
95 aligned to hold values of type \haddocktt{b}. The contents of the referenced
96 memory area will be the same as of the original pointer up to the
97 minimum of the original size and the size of values of type \haddocktt{b}.
98 \par
99 If the argument to \haddockid{realloc} is \haddockid{nullPtr}, \haddockid{realloc} behaves like
100 \haddockid{malloc}.
101 \par
102
103 \end{haddockdesc}
104 \begin{haddockdesc}
105 \item[\begin{tabular}{@{}l}
106 reallocBytes\ ::\ Ptr\ a\ ->\ Int\ ->\ IO\ (Ptr\ a)
107 \end{tabular}]\haddockbegindoc
108 Resize a memory area that was allocated with \haddockid{malloc} or \haddockid{mallocBytes}
109 to the given size. The returned pointer may refer to an entirely
110 different memory area, but will be sufficiently aligned for any of the
111 basic foreign types that fits into a memory block of the given size.
112 The contents of the referenced memory area will be the same as of
113 the original pointer up to the minimum of the original size and the
114 given size.
115 \par
116 If the pointer argument to \haddockid{reallocBytes} is \haddockid{nullPtr}, \haddockid{reallocBytes}
117 behaves like \haddockid{malloc}. If the requested size is 0, \haddockid{reallocBytes}
118 behaves like \haddockid{free}.
119 \par
120
121 \end{haddockdesc}
122 \begin{haddockdesc}
123 \item[\begin{tabular}{@{}l}
124 free\ ::\ Ptr\ a\ ->\ IO\ ()
125 \end{tabular}]\haddockbegindoc
126 Free a block of memory that was allocated with \haddockid{malloc},
127 \haddockid{mallocBytes}, \haddockid{realloc}, \haddockid{reallocBytes}, \haddocktt{Foreign.Marshal.Utils.new}
128 or any of the \haddocktt{new}\emph{X} functions in \haddocktt{Foreign.Marshal.Array} or
129 \haddocktt{Foreign.C.String}.
130 \par
131
132 \end{haddockdesc}
133 \begin{haddockdesc}
134 \item[\begin{tabular}{@{}l}
135 finalizerFree\ ::\ FinalizerPtr\ a
136 \end{tabular}]\haddockbegindoc
137 A pointer to a foreign function equivalent to \haddockid{free}, which may be
138 used as a finalizer (cf \haddocktt{Foreign.ForeignPtr.ForeignPtr}) for storage
139 allocated with \haddockid{malloc}, \haddockid{mallocBytes}, \haddockid{realloc} or \haddockid{reallocBytes}.
140 \par
141
142 \end{haddockdesc}