« back to all changes in this revision
Viewing changes to ocaml.html/manual032.html
- browse files at revision 4
- compare with another revision
- download diff
- download tarball
- view history from revision 4
- Committer: Bazaar Package Importer
- Author(s): Samuel Mimram
- Date: 2007-09-08 01:49:22 UTC
- mfrom: (0.1.3 upstream)
- Revision ID: james.westby@ubuntu.com-20070908014922-lvihyehz0ndq7suu
Tags: 3.10-1
* New upstream release.
* Removed camlp4 documentation since it is not up-to-date.
* Updated to standards version 3.7.2, no changes needed.
* Updated my email address.
* Removed camlp4 documentation since it is not up-to-date.
* Updated to standards version 3.7.2, no changes needed.
* Updated my email address.
- files added:
- examples/camlp4
- examples/ocamlbuild
- examples/ocamlbuild/example1
- examples/ocamlbuild/example2
- examples/ocamlbuild/example3
- examples/ocamlbuild/example_with_C
- files removed:
- camlp4-3.07-manual.dvi.gz
- camlp4-tutorial.html
- camlp4.html
- camlp4.html/lib
- examples/asl
- examples/basics
- examples/calc
- examples/camltk
- examples/camltk/images
- examples/camltktutorial
- examples/camltktutorial/servers
- examples/colwheel
- examples/compress
- examples/config
- examples/demonstr
- examples/dlls
- examples/docteur
- examples/doctor
- examples/grep
- examples/hanoi
- examples/kb
- examples/minicaml
- examples/minilogo
- examples/pascal
- examples/picomach
- examples/showsort
- examples/soli
- examples/spirals
- examples/tools
- files modified:
- debian/changelog
added
removed
ocaml.html/manual032.html
3
3
<HTML>
4
4
<HEAD>
5
5
6
7
8
6
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
9
<META name="GENERATOR" content="hevea 1.08">
7
<META name="GENERATOR" content="hevea 1.09">
10
8
<LINK rel="stylesheet" type="text/css" href="manual.css">
11
<TITLE>
12
Interfacing C with Objective Caml
13
</TITLE>
9
<TITLE>Interfacing C with Objective Caml</TITLE>
14
10
</HEAD>
15
11
<BODY >
16
<A HREF="manual031.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
17
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
18
<A HREF="manual033.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
12
<A HREF="manual031.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
13
<A HREF="index.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
14
<A HREF="manual033.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
19
15
<HR>
20
21
<H1 CLASS="chapter"><A NAME="htoc204">Chapter 18</A> Interfacing C with Objective Caml</H1> <A NAME="c:intf-c"></A>
22
23
This chapter describes how user-defined primitives, written in C, can
24
be linked with Caml code and called from Caml functions.<BR>
25
<BR>
26
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
27
Since 3.08.0 all global C identifiers have been prefixed with
28
"<KBD>caml_</KBD>" to avoid name clashes with other libraries (i.e.,
29
<KBD>caml_alloc_small</KBD> instead of <KBD>alloc_small</KBD>).
30
This change has been announced but has not been documented
31
before. These new "<KBD>caml_</KBD>" prefixes are not marked in
32
this page.
33
</div>
34
35
<H2 CLASS="section"><A NAME="htoc205">18.1</A> Overview and compilation information</H2>
36
37
38
<H3 CLASS="subsection"><A NAME="htoc206">18.1.1</A> Declaring primitives</H3>
16
<H1 CLASS="chapter"><A NAME="htoc204">Chapter�18</A>��Interfacing<A NAME="c:intf-c"></A> C with Objective Caml</H1><P>This chapter describes how user-defined primitives, written in C, can
17
be linked with Caml code and called from Caml functions.</P><H2 CLASS="section"><A NAME="htoc205">18.1</A>��Overview and compilation information</H2><H3 CLASS="subsection"><A NAME="htoc206">18.1.1</A>��Declaring primitives</H3><P>
39
18
User primitives are declared in an implementation file or
40
<TT>struct</TT>...<TT>end</TT> module expression using the <TT>external</TT> keyword:
41
<PRE>
19
<TT>struct</TT>…<TT>end</TT> module expression using the <TT>external</TT> keyword:
20
</P><PRE>
42
21
external <I>name</I> : <I>type</I> = <I>C-function-name</I>
43
</PRE>
22
</PRE><P>
44
23
This defines the value name <I>name</I> as a function with type
45
24
<I>type</I> that executes by calling the given C function.
46
25
For instance, here is how the <TT>input</TT> primitive is declared in the
47
26
standard library module <TT>Pervasives</TT>:
48
<PRE CLASS="verbatim">
49
external input : in_channel -> string -> int -> int -> int
27
</P><PRE CLASS="verbatim"> external input : in_channel -> string -> int -> int -> int
50
28
= "input"
51
</PRE>Primitives with several arguments are always curried. The C function
52
does not necessarily have the same name as the ML function.<BR>
53
<BR>
54
External functions thus defined can be specified in interface files or
55
<TT>sig</TT>...<TT>end</TT> signatures either as regular values
56
<PRE>
29
</PRE><P>Primitives with several arguments are always curried. The C function
30
does not necessarily have the same name as the ML function.</P><P>External functions thus defined can be specified in interface files or
31
<TT>sig</TT>…<TT>end</TT> signatures either as regular values
32
</P><PRE>
57
33
val <I>name</I> : <I>type</I>
58
</PRE>
34
</PRE><P>
59
35
thus hiding their implementation as a C function, or explicitly as
60
“manifest” external functions
61
<PRE>
36
“manifest” external functions
37
</P><PRE>
62
38
external <I>name</I> : <I>type</I> = <I>C-function-name</I>
63
</PRE>
39
</PRE><P>
64
40
The latter is slightly more efficient, as it allows clients of the
65
41
module to call directly the C function instead of going through the
66
corresponding Caml function. <BR>
67
<BR>
68
The arity (number of arguments) of a primitive is automatically
42
corresponding Caml function. </P><P>The arity (number of arguments) of a primitive is automatically
69
43
determined from its Caml type in the <TT>external</TT> declaration, by
70
44
counting the number of function arrows in the type. For instance,
71
45
<TT>input</TT> above has arity 4, and the <TT>input</TT> C function is called with
72
46
four arguments. Similarly,
73
<PRE CLASS="verbatim">
74
external input2 : in_channel * string * int * int -> int = "input2"
75
</PRE>has arity 1, and the <TT>input2</TT> C function receives one argument (which
76
is a quadruple of Caml values).<BR>
77
<BR>
78
Type abbreviations are not expanded when determining the arity of a
47
</P><PRE CLASS="verbatim"> external input2 : in_channel * string * int * int -> int = "input2"
48
</PRE><P>has arity 1, and the <TT>input2</TT> C function receives one argument (which
49
is a quadruple of Caml values).</P><P>Type abbreviations are not expanded when determining the arity of a
79
50
primitive. For instance,
80
<PRE CLASS="verbatim">
81
type int_endo = int -> int
51
</P><PRE CLASS="verbatim"> type int_endo = int -> int
82
52
external f : int_endo -> int_endo = "f"
83
53
external g : (int -> int) -> (int -> int) = "f"
84
</PRE><TT>f</TT> has arity 1, but <TT>g</TT> has arity 2. This allows a primitive to
54
</PRE><P><TT>f</TT> has arity 1, but <TT>g</TT> has arity 2. This allows a primitive to
85
55
return a functional value (as in the <TT>f</TT> example above): just remember
86
to name the functional return type in a type abbreviation.<BR>
87
<BR>
88
89
<H3 CLASS="subsection"><A NAME="htoc207">18.1.2</A> Implementing primitives</H3>
90
User primitives with arity <I>n</I> ≤ 5 are implemented by C functions
56
to name the functional return type in a type abbreviation.</P><H3 CLASS="subsection"><A NAME="htoc207">18.1.2</A>��Implementing primitives</H3><P>User primitives with arity <I>n</I> ≤ 5 are implemented by C functions
91
57
that take <I>n</I> arguments of type <TT>value</TT>, and return a result of type
92
58
<TT>value</TT>. The type <TT>value</TT> is the type of the representations for Caml
93
59
values. It encodes objects of several base types (integers,
94
floating-point numbers, strings, ...), as well as Caml data
60
floating-point numbers, strings, …), as well as Caml data
95
61
structures. The type <TT>value</TT> and the associated conversion
96
62
functions and macros are described in details below. For instance,
97
63
here is the declaration for the C function implementing the <TT>input</TT>
98
64
primitive:
99
<PRE CLASS="verbatim">
100
CAMLprim value input(value channel, value buffer, value offset, value length)
65
</P><PRE CLASS="verbatim">CAMLprim value input(value channel, value buffer, value offset, value length)
101
66
{
102
67
...
103
68
}
104
</PRE>When the primitive function is applied in a Caml program, the C
69
</PRE><P>When the primitive function is applied in a Caml program, the C
105
70
function is called with the values of the expressions to which the
106
71
primitive is applied as arguments. The value returned by the function is
107
72
passed back to the Caml program as the result of the function
108
application.<BR>
109
<BR>
110
User primitives with arity greater than 5 should be implemented by two
73
application.</P><P>User primitives with arity greater than 5 should be implemented by two
111
74
C functions. The first function, to be used in conjunction with the
112
75
bytecode compiler <TT>ocamlc</TT>, receives two arguments: a pointer to an
113
76
array of Caml values (the values for the arguments), and an
115
78
to be used in conjunction with the native-code compiler <TT>ocamlopt</TT>,
116
79
takes its arguments directly. For instance, here are the two C
117
80
functions for the 7-argument primitive <TT>Nat.add_nat</TT>:
118
<PRE CLASS="verbatim">
119
CAMLprim value add_nat_native(value nat1, value ofs1, value len1,
81
</P><PRE CLASS="verbatim">CAMLprim value add_nat_native(value nat1, value ofs1, value len1,
120
82
value nat2, value ofs2, value len2,
121
83
value carry_in)
122
84
{
127
89
return add_nat_native(argv[0], argv[1], argv[2], argv[3],
128
90
argv[4], argv[5], argv[6]);
129
91
}
130
</PRE>The names of the two C functions must be given in the primitive
92
</PRE><P>The names of the two C functions must be given in the primitive
131
93
declaration, as follows:
132
<PRE>
94
</P><PRE>
133
95
external <I>name</I> : <I>type</I> =
134
96
<I>bytecode-C-function-name native-code-C-function-name</I>
135
</PRE>
97
</PRE><P>
136
98
For instance, in the case of <TT>add_nat</TT>, the declaration is:
137
<PRE CLASS="verbatim">
138
external add_nat: nat -> int -> int -> nat -> int -> int -> int -> int
99
</P><PRE CLASS="verbatim"> external add_nat: nat -> int -> int -> nat -> int -> int -> int -> int
139
100
= "add_nat_bytecode" "add_nat_native"
140
</PRE>
141
Implementing a user primitive is actually two separate tasks: on the
101
</PRE><P>Implementing a user primitive is actually two separate tasks: on the
142
102
one hand, decoding the arguments to extract C values from the given
143
103
Caml values, and encoding the return value as a Caml
144
104
value; on the other hand, actually computing the result from the arguments.
146
106
distinct C functions to implement these two tasks. The first function
147
107
actually implements the primitive, taking native C values as
148
108
arguments and returning a native C value. The second function,
149
often called the “stub code”, is a simple wrapper around the first
109
often called the “stub code”, is a simple wrapper around the first
150
110
function that converts its arguments from Caml values to C values,
151
111
call the first function, and convert the returned C value to Caml
152
112
value. For instance, here is the stub code for the <TT>input</TT>
153
113
primitive:
154
<PRE CLASS="verbatim">
155
CAMLprim value input(value channel, value buffer, value offset, value length)
114
</P><PRE CLASS="verbatim">CAMLprim value input(value channel, value buffer, value offset, value length)
156
115
{
157
116
return Val_long(getblock((struct channel *) channel,
158
117
&Byte(buffer, Long_val(offset)),
159
118
Long_val(length)));
160
119
}
161
</PRE>(Here, <TT>Val_long</TT>, <TT>Long_val</TT> and so on are conversion macros for the
120
</PRE><P>(Here, <TT>Val_long</TT>, <TT>Long_val</TT> and so on are conversion macros for the
162
121
type <TT>value</TT>, that will be described later. The <TT>CAMLprim</TT> macro
163
122
expands to the required compiler directives to ensure that the
164
123
function following it is exported and accessible from Caml.)
165
124
The hard work is performed by the function <TT>getblock</TT>, which is
166
125
declared as:
167
<PRE CLASS="verbatim">
168
long getblock(struct channel * channel, char * p, long n)
126
</P><PRE CLASS="verbatim">long getblock(struct channel * channel, char * p, long n)
169
127
{
170
128
...
171
129
}
172
</PRE>
173
To write C code that operates on Objective Caml values, the following
130
</PRE><P>To write C code that operates on Objective Caml values, the following
174
131
include files are provided:
175
<BR>
176
<BR>
177
<DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
178
<TR><TD ALIGN=center NOWRAP><B>Include file</B></TD>
179
<TD ALIGN=center NOWRAP><B>Provides</B></TD>
180
</TR>
132
</P><DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%"><TR><TD ALIGN=center NOWRAP><B>Include file</B></TD><TD ALIGN=center NOWRAP><B>Provides</B></TD></TR>
181
133
<TR><TD VALIGN=top ALIGN=left NOWRAP>
182
<TT>caml/mlvalues.h</TT></TD>
183
<TD VALIGN=top ALIGN=left>definition of the <TT>value</TT> type, and conversion macros</TD>
184
</TR>
185
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/alloc.h</TT></TD>
186
<TD VALIGN=top ALIGN=left>allocation functions (to create structured Caml
187
objects)</TD>
188
</TR>
189
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/memory.h</TT></TD>
190
<TD VALIGN=top ALIGN=left>miscellaneous memory-related functions
191
and macros (for GC interface, in-place modification of structures, etc).</TD>
192
</TR>
193
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/fail.h</TT></TD>
194
<TD VALIGN=top ALIGN=left>functions for raising exceptions
195
(see section <A HREF="#s:c-exceptions">18.4.5</A>)</TD>
196
</TR>
197
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/callback.h</TT></TD>
198
<TD VALIGN=top ALIGN=left>callback from C to Caml (see
199
section <A HREF="#s:callback">18.7</A>).</TD>
200
</TR>
201
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/custom.h</TT></TD>
202
<TD VALIGN=top ALIGN=left>operations on custom blocks (see
203
section <A HREF="#s:custom">18.9</A>).</TD>
204
</TR>
205
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/intext.h</TT></TD>
206
<TD VALIGN=top ALIGN=left>operations for writing user-defined
134
<TT>caml/mlvalues.h</TT></TD><TD VALIGN=top ALIGN=left>definition of the <TT>value</TT> type, and conversion macros</TD></TR>
135
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/alloc.h</TT></TD><TD VALIGN=top ALIGN=left>allocation functions (to create structured Caml
136
objects)</TD></TR>
137
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/memory.h</TT></TD><TD VALIGN=top ALIGN=left>miscellaneous memory-related functions
138
and macros (for GC interface, in-place modification of structures, etc).</TD></TR>
139
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/fail.h</TT></TD><TD VALIGN=top ALIGN=left>functions for raising exceptions
140
(see section�<A HREF="#s:c-exceptions">18.4.5</A>)</TD></TR>
141
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/callback.h</TT></TD><TD VALIGN=top ALIGN=left>callback from C to Caml (see
142
section�<A HREF="#s:callback">18.7</A>).</TD></TR>
143
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/custom.h</TT></TD><TD VALIGN=top ALIGN=left>operations on custom blocks (see
144
section�<A HREF="#s:custom">18.9</A>).</TD></TR>
145
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml/intext.h</TT></TD><TD VALIGN=top ALIGN=left>operations for writing user-defined
207
146
serialization and deserialization functions for custom blocks
208
(see section <A HREF="#s:custom">18.9</A>).</TD>
209
</TR></TABLE></DIV><BR>
210
<BR>
211
147
(see section�<A HREF="#s:custom">18.9</A>).</TD></TR>
148
</TABLE></DIV><P>
212
149
These files reside in the <TT>caml/</TT> subdirectory of the Objective Caml
213
standard library directory (usually <TT>/usr/local/lib/ocaml</TT>).<BR>
214
<BR>
215
216
<H3 CLASS="subsection"><A NAME="htoc208">18.1.3</A> Statically linking C code with Caml code</H3>
217
<A NAME="staticlink-c-code"></A>
218
The Objective Caml runtime system comprises three main parts: the bytecode
150
standard library directory (usually <TT>/usr/local/lib/ocaml</TT>).</P><H3 CLASS="subsection"><A NAME="htoc208">18.1.3</A>��Statically linking C code with Caml code</H3><P>
151
<A NAME="staticlink-c-code"></A></P><P>The Objective Caml runtime system comprises three main parts: the bytecode
219
152
interpreter, the memory manager, and a set of C functions that
220
153
implement the primitive operations. Some bytecode instructions are
221
154
provided to call these C functions, designated by their offset in a
222
table of functions (the table of primitives).<BR>
223
<BR>
224
In the default mode, the Caml linker produces bytecode for the
155
table of functions (the table of primitives).</P><P>In the default mode, the Caml linker produces bytecode for the
225
156
standard runtime system, with a standard set of primitives. References
226
157
to primitives that are not in this standard set result in the
227
“unavailable C primitive” error. (Unless dynamic loading of C
228
libraries is supported – see section <A HREF="#dynlink-c-code">18.1.4</A> below.)<BR>
229
<BR>
230
In the “custom runtime” mode, the Caml linker scans the
158
“unavailable C primitive” error. (Unless dynamic loading of C
159
libraries is supported – see section�<A HREF="#dynlink-c-code">18.1.4</A> below.)</P><P>In the “custom runtime” mode, the Caml linker scans the
231
160
object files and determines the set of required primitives. Then, it
232
161
builds a suitable runtime system, by calling the native code linker with:
233
<UL CLASS="itemize"><LI CLASS="li-itemize">
162
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
234
163
the table of the required primitives;
235
<LI CLASS="li-itemize">a library that provides the bytecode interpreter, the
164
</LI><LI CLASS="li-itemize">a library that provides the bytecode interpreter, the
236
165
memory manager, and the standard primitives;
237
<LI CLASS="li-itemize">libraries and object code files (<TT>.o</TT> files) mentioned on the
166
</LI><LI CLASS="li-itemize">libraries and object code files (<TT>.o</TT> files) mentioned on the
238
167
command line for the Caml linker, that provide implementations
239
168
for the user's primitives.
240
</UL>
169
</LI></UL><P>
241
170
This builds a runtime system with the required primitives. The Caml
242
171
linker generates bytecode for this custom runtime system. The
243
172
bytecode is appended to the end of the custom runtime system, so that
244
173
it will be automatically executed when the output file (custom
245
runtime + bytecode) is launched.<BR>
246
<BR>
247
To link in “custom runtime” mode, execute the <TT>ocamlc</TT> command with:
248
<UL CLASS="itemize"><LI CLASS="li-itemize">
174
runtime + bytecode) is launched.</P><P>To link in “custom runtime” mode, execute the <TT>ocamlc</TT> command with:
175
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
249
176
the <TT>-custom</TT> option;
250
<LI CLASS="li-itemize">the names of the desired Caml object files (<TT>.cmo</TT> and <TT>.cma</TT> files) ;
251
<LI CLASS="li-itemize">the names of the C object files and libraries (<TT>.o</TT> and <TT>.a</TT>
177
</LI><LI CLASS="li-itemize">the names of the desired Caml object files (<TT>.cmo</TT> and <TT>.cma</TT> files) ;
178
</LI><LI CLASS="li-itemize">the names of the C object files and libraries (<TT>.o</TT> and <TT>.a</TT>
252
179
files) that implement the required primitives. Under Unix and Windows,
253
180
a library named <TT>lib</TT><I>name</I><TT>.a</TT> residing in one of the standard
254
181
library directories can also be specified as <TT>-cclib -l</TT><I>name</I>.
255
</UL>
256
If you are using the native-code compiler <TT>ocamlopt</TT>, the <TT>-custom</TT>
182
</LI></UL><P>If you are using the native-code compiler <TT>ocamlopt</TT>, the <TT>-custom</TT>
257
183
flag is not needed, as the final linking phase of <TT>ocamlopt</TT> always
258
184
builds a standalone executable. To build a mixed Caml/C executable,
259
185
execute the <TT>ocamlopt</TT> command with:
260
<UL CLASS="itemize"><LI CLASS="li-itemize">
186
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
261
187
the names of the desired Caml native object files (<TT>.cmx</TT> and
262
188
<TT>.cmxa</TT> files);
263
<LI CLASS="li-itemize">the names of the C object files and libraries (<TT>.o</TT>, <TT>.a</TT>,
189
</LI><LI CLASS="li-itemize">the names of the C object files and libraries (<TT>.o</TT>, <TT>.a</TT>,
264
190
<TT>.so</TT> or <TT>.dll</TT> files) that implement the required primitives.
265
</UL>
266
Starting with OCaml 3.00, it is possible to record the
191
</LI></UL><P>Starting with OCaml 3.00, it is possible to record the
267
192
<TT>-custom</TT> option as well as the names of C libraries in a Caml
268
193
library file <TT>.cma</TT> or <TT>.cmxa</TT>. For instance, consider a Caml library
269
194
<TT>mylib.cma</TT>, built from the Caml object files <TT>a.cmo</TT> and <TT>b.cmo</TT>,
270
195
which reference C code in <TT>libmylib.a</TT>. If the library is
271
196
built as follows:
272
<PRE>
197
</P><PRE>
273
198
ocamlc -a -o mylib.cma -custom a.cmo b.cmo -cclib -lmylib
274
</PRE>
199
</PRE><P>
275
200
users of the library can simply link with <TT>mylib.cma</TT>:
276
<PRE>
201
</P><PRE>
277
202
ocamlc -o myprog mylib.cma ...
278
</PRE>
203
</PRE><P>
279
204
and the system will automatically add the <TT>-custom</TT> and <TT>-cclib -lmylib</TT> options, achieving the same effect as
280
<PRE>
205
</P><PRE>
281
206
ocamlc -o myprog -custom a.cmo b.cmo ... -cclib -lmylib
282
</PRE>
207
</PRE><P>
283
208
The alternative, of course, is to build the library without extra
284
209
options:
285
<PRE>
210
</P><PRE>
286
211
ocamlc -a -o mylib.cma a.cmo b.cmo
287
</PRE>
212
</PRE><P>
288
213
and then ask users to provide the <TT>-custom</TT> and <TT>-cclib -lmylib</TT>
289
214
options themselves at link-time:
290
<PRE>
215
</P><PRE>
291
216
ocamlc -o myprog -custom mylib.cma ... -cclib -lmylib
292
</PRE>
217
</PRE><P>
293
218
The former alternative is more convenient for the final users of the
294
library, however.<BR>
295
<BR>
296
297
<H3 CLASS="subsection"><A NAME="htoc209">18.1.4</A> Dynamically linking C code with Caml code</H3>
298
<A NAME="dynlink-c-code"></A>
299
Starting with OCaml 3.03, an alternative to static linking of C code
219
library, however.</P><H3 CLASS="subsection"><A NAME="htoc209">18.1.4</A>��Dynamically linking C code with Caml code</H3><P>
220
<A NAME="dynlink-c-code"></A></P><P>Starting with OCaml 3.03, an alternative to static linking of C code
300
221
using the <TT>-custom</TT> code is provided. In this mode, the Caml linker
301
222
generates a pure bytecode executable (no embedded custom runtime
302
223
system) that simply records the names of dynamically-loaded libraries
303
224
containing the C code. The standard Caml runtime system <TT>ocamlrun</TT>
304
225
then loads dynamically these libraries, and resolves references to the
305
required primitives, before executing the bytecode.<BR>
306
<BR>
307
This facility is currently supported and known to work well under
308
Linux and Windows (the native Windows port). It is supported, but not
226
required primitives, before executing the bytecode.</P><P>This facility is currently supported and known to work well under
227
Linux, MacOS�X, and Windows (the native Windows port). It is supported, but not
309
228
fully tested yet, under FreeBSD, Tru64, Solaris and Irix. It is not
310
supported yet under other Unixes, Cygwin for Windows, and MacOS.<BR>
311
<BR>
312
To dynamically link C code with Caml code, the C code must first be
229
supported yet under other Unixes and under Cygwin for Windows.</P><P>To dynamically link C code with Caml code, the C code must first be
313
230
compiled into a shared library (under Unix) or DLL (under Windows).
314
231
This involves 1- compiling the C files with appropriate C compiler
315
232
flags for producing position-independent code, and 2- building a
316
233
shared library from the resulting object files. The resulting shared
317
234
library or DLL file must be installed in a place where <TT>ocamlrun</TT> can
318
235
find it later at program start-up time (see
319
section <A HREF="manual024.html#s-ocamlrun-dllpath">10.3</A>).
236
section�<A HREF="manual024.html#s-ocamlrun-dllpath">10.3</A>).
320
237
Finally (step 3), execute the <TT>ocamlc</TT> command with
321
<UL CLASS="itemize"><LI CLASS="li-itemize">
238
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
322
239
the names of the desired Caml object files (<TT>.cmo</TT> and <TT>.cma</TT> files) ;
323
<LI CLASS="li-itemize">the names of the C shared libraries (<TT>.so</TT> or <TT>.dll</TT> files) that
240
</LI><LI CLASS="li-itemize">the names of the C shared libraries (<TT>.so</TT> or <TT>.dll</TT> files) that
324
241
implement the required primitives. Under Unix and Windows,
325
242
a library named <TT>dll</TT><I>name</I><TT>.so</TT> (respectively, <TT>.dll</TT>) residing
326
243
in one of the standard library directories can also be specified as
327
244
<TT>-dllib -l</TT><I>name</I>.
328
</UL>
245
</LI></UL><P>
329
246
Do <EM>not</EM> set the <TT>-custom</TT> flag, otherwise you're back to static linking
330
as described in section <A HREF="#staticlink-c-code">18.1.3</A>.
331
Under Unix, the <TT>ocamlmklib</TT> tool (see section <A HREF="#s-ocamlmklib">18.10</A>)
332
automates steps 2 and 3.<BR>
333
<BR>
334
As in the case of static linking, it is possible (and recommended) to
247
as described in section�<A HREF="#staticlink-c-code">18.1.3</A>.
248
Under Unix, the <TT>ocamlmklib</TT> tool (see section�<A HREF="#s-ocamlmklib">18.10</A>)
249
automates steps 2 and 3.</P><P>As in the case of static linking, it is possible (and recommended) to
335
250
record the names of C libraries in a Caml <TT>.cmo</TT> library archive.
336
251
Consider again a Caml library
337
252
<TT>mylib.cma</TT>, built from the Caml object files <TT>a.cmo</TT> and <TT>b.cmo</TT>,
338
253
which reference C code in <TT>dllmylib.so</TT>. If the library is
339
254
built as follows:
340
<PRE>
255
</P><PRE>
341
256
ocamlc -a -o mylib.cma a.cmo b.cmo -dllib -lmylib
342
</PRE>
257
</PRE><P>
343
258
users of the library can simply link with <TT>mylib.cma</TT>:
344
<PRE>
259
</P><PRE>
345
260
ocamlc -o myprog mylib.cma ...
346
</PRE>
261
</PRE><P>
347
262
and the system will automatically add the <TT>-dllib -lmylib</TT> option,
348
263
achieving the same effect as
349
<PRE>
264
</P><PRE>
350
265
ocamlc -o myprog a.cmo b.cmo ... -dllib -lmylib
351
</PRE>
266
</PRE><P>
352
267
Using this mechanism, users of the library <TT>mylib.cma</TT> do not need to
353
268
known that it references C code, nor whether this C code must be
354
statically linked (using <TT>-custom</TT>) or dynamically linked.<BR>
355
<BR>
356
357
<H3 CLASS="subsection"><A NAME="htoc210">18.1.5</A> Choosing between static linking and dynamic linking</H3>
358
After having described two different ways of linking C code with Caml
269
statically linked (using <TT>-custom</TT>) or dynamically linked.</P><H3 CLASS="subsection"><A NAME="htoc210">18.1.5</A>��Choosing between static linking and dynamic linking</H3><P>After having described two different ways of linking C code with Caml
359
270
code, we now review the pros and cons of each, to help developers of
360
mixed Caml/C libraries decide.<BR>
361
<BR>
362
The main advantage of dynamic linking is that it preserves the
271
mixed Caml/C libraries decide.</P><P>The main advantage of dynamic linking is that it preserves the
363
272
platform-independence of bytecode executables. That is, the bytecode
364
273
executable contains no machine code, and can therefore be compiled on
365
platform <I>A</I> and executed on other platforms <I>B</I>, <I>C</I>, ..., as long
274
platform <I>A</I> and executed on other platforms <I>B</I>, <I>C</I>, …, as long
366
275
as the required shared libraries are available on all these
367
276
platforms. In contrast, executables generated by <TT>ocamlc -custom</TT> run
368
277
only on the platform on which they were created, because they embark a
369
278
custom-tailored runtime system specific to that platform. In
370
addition, dynamic linking results in smaller executables.<BR>
371
<BR>
372
Another advantage of dynamic linking is that the final users of the
279
addition, dynamic linking results in smaller executables.</P><P>Another advantage of dynamic linking is that the final users of the
373
280
library do not need to have a C compiler, C linker, and C runtime
374
281
libraries installed on their machines. This is no big deal under
375
282
Unix and Cygwin, but many Windows users are reluctant to install
376
Microsoft Visual C just to be able to do <TT>ocamlc -custom</TT>.<BR>
377
<BR>
378
There are two drawbacks to dynamic linking. The first is that the
283
Microsoft Visual C just to be able to do <TT>ocamlc -custom</TT>.</P><P>There are two drawbacks to dynamic linking. The first is that the
379
284
resulting executable is not stand-alone: it requires the shared
380
285
libraries, as well as <TT>ocamlrun</TT>, to be installed on the machine
381
286
executing the code. If you wish to distribute a stand-alone
382
287
executable, it is better to link it statically, using <TT>ocamlc -custom -ccopt -static</TT> or <TT>ocamlopt -ccopt -static</TT>. Dynamic linking also
383
raises the “DLL hell” problem: some care must be taken to ensure
288
raises the “DLL hell” problem: some care must be taken to ensure
384
289
that the right versions of the shared libraries are found at start-up
385
time.<BR>
386
<BR>
387
The second drawback of dynamic linking is that it complicates the
290
time.</P><P>The second drawback of dynamic linking is that it complicates the
388
291
construction of the library. The C compiler and linker flags to
389
292
compile to position-independent code and build a shared library vary
390
293
wildly between different Unix systems. Also, dynamic linking is not
391
294
supported on all Unix systems, requiring a fall-back case to static
392
295
linking in the Makefile for the library. The <TT>ocamlmklib</TT> command
393
(see section <A HREF="#s-ocamlmklib">18.10</A>) tries to hide some of these system
394
dependencies.<BR>
395
<BR>
396
In conclusion: dynamic linking is highly recommended under the native
296
(see section�<A HREF="#s-ocamlmklib">18.10</A>) tries to hide some of these system
297
dependencies.</P><P>In conclusion: dynamic linking is highly recommended under the native
397
298
Windows port, because there are no portability problems and it is much
398
299
more convenient for the end users. Under Unix, dynamic linking should
399
300
be considered for mature, frequently used libraries because it
400
301
enhances platform-independence of bytecode executables. For new or
401
302
rarely-used libraries, static linking is much simpler to set up in a
402
portable way.<BR>
403
<BR>
404
405
<H3 CLASS="subsection"><A NAME="htoc211">18.1.6</A> Building standalone custom runtime systems</H3>
406
<A NAME="s:custom-runtime"></A>
407
It is sometimes inconvenient to build a custom runtime system each
303
portable way.</P><H3 CLASS="subsection"><A NAME="htoc211">18.1.6</A>��Building standalone custom runtime systems</H3><P>
304
<A NAME="s:custom-runtime"></A></P><P>It is sometimes inconvenient to build a custom runtime system each
408
305
time Caml code is linked with C libraries, like <TT>ocamlc -custom</TT> does.
409
306
For one thing, the building of the runtime system is slow on some
410
307
systems (that have bad linkers or slow remote file systems); for
411
308
another thing, the platform-independence of bytecode files is lost,
412
forcing to perform one <TT>ocamlc -custom</TT> link per platform of interest.<BR>
413
<BR>
414
An alternative to <TT>ocamlc -custom</TT> is to build separately a custom
309
forcing to perform one <TT>ocamlc -custom</TT> link per platform of interest.</P><P>An alternative to <TT>ocamlc -custom</TT> is to build separately a custom
415
310
runtime system integrating the desired C libraries, then generate
416
“pure” bytecode executables (not containing their own runtime
311
“pure” bytecode executables (not containing their own runtime
417
312
system) that can run on this custom runtime. This is achieved by the
418
313
<TT>-make_runtime</TT> and <TT>-use_runtime</TT> flags to <TT>ocamlc</TT>. For example,
419
314
to build a custom runtime system integrating the C parts of the
420
“Unix” and “Threads” libraries, do:
421
<PRE CLASS="verbatim">
422
ocamlc -make-runtime -o /home/me/ocamlunixrun unix.cma threads.cma
423
</PRE>To generate a bytecode executable that runs on this runtime system,
315
“Unix” and “Threads” libraries, do:
316
</P><PRE CLASS="verbatim"> ocamlc -make-runtime -o /home/me/ocamlunixrun unix.cma threads.cma
317
</PRE><P>To generate a bytecode executable that runs on this runtime system,
424
318
do:
425
<PRE>
319
</P><PRE>
426
320
ocamlc -use-runtime /home/me/ocamlunixrun -o myprog \
427
321
unix.cma threads.cma <I>your .cmo and .cma files</I>
428
</PRE>
322
</PRE><P>
429
323
The bytecode executable <TT>myprog</TT> can then be launched as usual:
430
<TT>myprog</TT> <I>args</I> or <TT>/home/me/ocamlunixrun myprog</TT> <I>args</I>.<BR>
431
<BR>
432
Notice that the bytecode libraries <TT>unix.cma</TT> and <TT>threads.cma</TT> must
324
<TT>myprog</TT> <I>args</I> or <TT>/home/me/ocamlunixrun myprog</TT> <I>args</I>.</P><P>Notice that the bytecode libraries <TT>unix.cma</TT> and <TT>threads.cma</TT> must
433
325
be given twice: when building the runtime system (so that <TT>ocamlc</TT>
434
326
knows which C primitives are required) and also when building the
435
327
bytecode executable (so that the bytecode from <TT>unix.cma</TT> and
436
<TT>threads.cma</TT> is actually linked in).<BR>
437
<BR>
438
439
<H2 CLASS="section"><A NAME="htoc212">18.2</A> The <TT>value</TT> type</H2>
440
441
All Caml objects are represented by the C type <TT>value</TT>,
328
<TT>threads.cma</TT> is actually linked in).</P><H2 CLASS="section"><A NAME="htoc212">18.2</A>��The <TT>value</TT> type</H2><P>All Caml objects are represented by the C type <TT>value</TT>,
442
329
defined in the include file <TT>caml/mlvalues.h</TT>, along with macros to
443
330
manipulate values of that type. An object of type <TT>value</TT> is either:
444
<UL CLASS="itemize"><LI CLASS="li-itemize">
331
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
445
332
an unboxed integer;
446
<LI CLASS="li-itemize">a pointer to a block inside the heap (such as the blocks
333
</LI><LI CLASS="li-itemize">a pointer to a block inside the heap (such as the blocks
447
334
allocated through one of the <CODE>caml_alloc_*</CODE> functions below);
448
<LI CLASS="li-itemize">a pointer to an object outside the heap (e.g., a pointer to a block
335
</LI><LI CLASS="li-itemize">a pointer to an object outside the heap (e.g., a pointer to a block
449
336
allocated by <TT>malloc</TT>, or to a C variable).
450
</UL>
451
452
<H3 CLASS="subsection"><A NAME="htoc213">18.2.1</A> Integer values</H3>
453
Integer values encode 31-bit signed integers (63-bit on 64-bit
454
architectures). They are unboxed (unallocated).<BR>
455
<BR>
456
457
<H3 CLASS="subsection"><A NAME="htoc214">18.2.2</A> Blocks</H3>
458
Blocks in the heap are garbage-collected, and therefore have strict
337
</LI></UL><H3 CLASS="subsection"><A NAME="htoc213">18.2.1</A>��Integer values</H3><P>Integer values encode 31-bit signed integers (63-bit on 64-bit
338
architectures). They are unboxed (unallocated).</P><H3 CLASS="subsection"><A NAME="htoc214">18.2.2</A>��Blocks</H3><P>Blocks in the heap are garbage-collected, and therefore have strict
459
339
structure constraints. Each block includes a header containing the
460
340
size of the block (in words), and the tag of the block.
461
341
The tag governs how the contents of the blocks are structured. A tag
466
346
For the benefits of ad-hoc polymorphic primitives such as equality and
467
347
structured input-output, structured and raw blocks are further
468
348
classified according to their tags as follows:
469
<BR>
470
<BR>
471
<DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
472
<TR><TD ALIGN=center NOWRAP><B>Tag</B></TD>
473
<TD ALIGN=center NOWRAP><B>Contents of the block</B></TD>
474
</TR>
349
</P><DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%"><TR><TD ALIGN=center NOWRAP><B>Tag</B></TD><TD ALIGN=center NOWRAP><B>Contents of the block</B></TD></TR>
475
350
<TR><TD VALIGN=top ALIGN=left NOWRAP>
476
0 to <TT>No_scan_tag</TT>−1</TD>
477
<TD VALIGN=top ALIGN=left>A structured block (an array of
478
Caml objects). Each field is a <TT>value</TT>.</TD>
479
</TR>
480
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Closure_tag</TT></TD>
481
<TD VALIGN=top ALIGN=left>A closure representing a functional value. The first
351
0 to <TT>No_scan_tag</TT>−1</TD><TD VALIGN=top ALIGN=left>A structured block (an array of
352
Caml objects). Each field is a <TT>value</TT>.</TD></TR>
353
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Closure_tag</TT></TD><TD VALIGN=top ALIGN=left>A closure representing a functional value. The first
482
354
word is a pointer to a piece of code, the remaining words are
483
<TT>value</TT> containing the environment.</TD>
484
</TR>
485
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>String_tag</TT></TD>
486
<TD VALIGN=top ALIGN=left>A character string.</TD>
487
</TR>
488
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Double_tag</TT></TD>
489
<TD VALIGN=top ALIGN=left>A double-precision floating-point number.</TD>
490
</TR>
491
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Double_array_tag</TT></TD>
492
<TD VALIGN=top ALIGN=left>An array or record of double-precision
493
floating-point numbers.</TD>
494
</TR>
495
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Abstract_tag</TT></TD>
496
<TD VALIGN=top ALIGN=left>A block representing an abstract datatype.</TD>
497
</TR>
498
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Custom_tag</TT></TD>
499
<TD VALIGN=top ALIGN=left>A block representing an abstract datatype
500
with user-defined finalization, comparison, hashing,
501
serialization and deserialization functions atttached.</TD>
502
</TR></TABLE></DIV><BR>
503
<BR>
504
505
<H3 CLASS="subsection"><A NAME="htoc215">18.2.3</A> Pointers outside the heap</H3>
506
Any word-aligned pointer to an address outside the heap can be safely
355
<TT>value</TT> containing the environment.</TD></TR>
356
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>String_tag</TT></TD><TD VALIGN=top ALIGN=left>A character string.</TD></TR>
357
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Double_tag</TT></TD><TD VALIGN=top ALIGN=left>A double-precision floating-point number.</TD></TR>
358
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Double_array_tag</TT></TD><TD VALIGN=top ALIGN=left>An array or record of double-precision
359
floating-point numbers.</TD></TR>
360
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Abstract_tag</TT></TD><TD VALIGN=top ALIGN=left>A block representing an abstract datatype.</TD></TR>
361
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>Custom_tag</TT></TD><TD VALIGN=top ALIGN=left>A block representing an abstract datatype
362
with user-defined finalization, comparison, hashing,
363
serialization and deserialization functions atttached.</TD></TR>
364
</TABLE></DIV><H3 CLASS="subsection"><A NAME="htoc215">18.2.3</A>��Pointers outside the heap</H3><P>Any word-aligned pointer to an address outside the heap can be safely
507
365
cast to and from the type <TT>value</TT>. This includes pointers returned by
508
366
<TT>malloc</TT>, and pointers to C variables (of size at least one word)
509
obtained with the <CODE>&</CODE> operator.<BR>
510
<BR>
511
Caution: if a pointer returned by <TT>malloc</TT> is cast to the type <TT>value</TT>
367
obtained with the <CODE>&</CODE> operator.</P><P>Caution: if a pointer returned by <TT>malloc</TT> is cast to the type <TT>value</TT>
512
368
and returned to Caml, explicit deallocation of the pointer using
513
369
<TT>free</TT> is potentially dangerous, because the pointer may still be
514
370
accessible from the Caml world. Worse, the memory space deallocated
516
372
pointer, formerly pointing outside the Caml heap, now points inside
517
373
the Caml heap, and this can confuse the garbage collector. To avoid
518
374
these problems, it is preferable to wrap the pointer in a Caml block
519
with tag <TT>Abstract_tag</TT> or <TT>Custom_tag</TT>.<BR>
520
<BR>
521
522
<H2 CLASS="section"><A NAME="htoc216">18.3</A> Representation of Caml data types</H2>
523
524
This section describes how Caml data types are encoded in the
525
<TT>value</TT> type.<BR>
526
<BR>
527
528
<H3 CLASS="subsection"><A NAME="htoc217">18.3.1</A> Atomic types</H3><BR>
529
<BR>
530
<DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
531
<TR><TD ALIGN=center NOWRAP><B>Caml type</B></TD>
532
<TD ALIGN=center NOWRAP><B>Encoding</B></TD>
533
</TR>
375
with tag <TT>Abstract_tag</TT> or <TT>Custom_tag</TT>.</P><H2 CLASS="section"><A NAME="htoc216">18.3</A>��Representation of Caml data types</H2><P>This section describes how Caml data types are encoded in the
376
<TT>value</TT> type.</P><H3 CLASS="subsection"><A NAME="htoc217">18.3.1</A>��Atomic types</H3><DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%"><TR><TD ALIGN=center NOWRAP><B>Caml type</B></TD><TD ALIGN=center NOWRAP><B>Encoding</B></TD></TR>
534
377
<TR><TD ALIGN=left NOWRAP>
535
<TT>int</TT></TD>
536
<TD ALIGN=left NOWRAP>Unboxed integer values.</TD>
537
</TR>
538
<TR><TD ALIGN=left NOWRAP><TT>char</TT></TD>
539
<TD ALIGN=left NOWRAP>Unboxed integer values (ASCII code).</TD>
540
</TR>
541
<TR><TD ALIGN=left NOWRAP><TT>float</TT></TD>
542
<TD ALIGN=left NOWRAP>Blocks with tag <TT>Double_tag</TT>.</TD>
543
</TR>
544
<TR><TD ALIGN=left NOWRAP><TT>string</TT></TD>
545
<TD ALIGN=left NOWRAP>Blocks with tag <TT>String_tag</TT>.</TD>
546
</TR>
547
<TR><TD ALIGN=left NOWRAP><TT>int32</TT></TD>
548
<TD ALIGN=left NOWRAP>Blocks with tag <TT>Custom_tag</TT>.</TD>
549
</TR>
550
<TR><TD ALIGN=left NOWRAP><TT>int64</TT></TD>
551
<TD ALIGN=left NOWRAP>Blocks with tag <TT>Custom_tag</TT>.</TD>
552
</TR>
553
<TR><TD ALIGN=left NOWRAP><TT>nativeint</TT></TD>
554
<TD ALIGN=left NOWRAP>Blocks with tag <TT>Custom_tag</TT>.</TD>
555
</TR></TABLE></DIV><BR>
556
<BR>
557
558
<H3 CLASS="subsection"><A NAME="htoc218">18.3.2</A> Tuples and records</H3>
559
Tuples are represented by pointers to blocks, with tag 0.<BR>
560
<BR>
561
Records are also represented by zero-tagged blocks. The ordering of
378
<TT>int</TT></TD><TD ALIGN=left NOWRAP>Unboxed integer values.</TD></TR>
379
<TR><TD ALIGN=left NOWRAP><TT>char</TT></TD><TD ALIGN=left NOWRAP>Unboxed integer values (ASCII code).</TD></TR>
380
<TR><TD ALIGN=left NOWRAP><TT>float</TT></TD><TD ALIGN=left NOWRAP>Blocks with tag <TT>Double_tag</TT>.</TD></TR>
381
<TR><TD ALIGN=left NOWRAP><TT>string</TT></TD><TD ALIGN=left NOWRAP>Blocks with tag <TT>String_tag</TT>.</TD></TR>
382
<TR><TD ALIGN=left NOWRAP><TT>int32</TT></TD><TD ALIGN=left NOWRAP>Blocks with tag <TT>Custom_tag</TT>.</TD></TR>
383
<TR><TD ALIGN=left NOWRAP><TT>int64</TT></TD><TD ALIGN=left NOWRAP>Blocks with tag <TT>Custom_tag</TT>.</TD></TR>
384
<TR><TD ALIGN=left NOWRAP><TT>nativeint</TT></TD><TD ALIGN=left NOWRAP>Blocks with tag <TT>Custom_tag</TT>.</TD></TR>
385
</TABLE></DIV><H3 CLASS="subsection"><A NAME="htoc218">18.3.2</A>��Tuples and records</H3><P>Tuples are represented by pointers to blocks, with tag�0.</P><P>Records are also represented by zero-tagged blocks. The ordering of
562
386
labels in the record type declaration determines the layout of
563
387
the record fields: the value associated to the label
564
declared first is stored in field 0 of the block, the value associated
565
to the label declared next goes in field 1, and so on.<BR>
566
<BR>
567
As an optimization, records whose fields all have static type <TT>float</TT>
388
declared first is stored in field�0 of the block, the value associated
389
to the label declared next goes in field�1, and so on.</P><P>As an optimization, records whose fields all have static type <TT>float</TT>
568
390
are represented as arrays of floating-point numbers, with tag
569
<TT>Double_array_tag</TT>. (See the section below on arrays.)<BR>
570
<BR>
571
572
<H3 CLASS="subsection"><A NAME="htoc219">18.3.3</A> Arrays</H3>
573
Arrays of integers and pointers are represented like tuples,
574
that is, as pointers to blocks tagged 0. They are accessed with the
575
<TT>Field</TT> macro for reading and the <TT>modify</TT> function for writing.<BR>
576
<BR>
577
Arrays of floating-point numbers (type <TT>float array</TT>)
391
<TT>Double_array_tag</TT>. (See the section below on arrays.)</P><H3 CLASS="subsection"><A NAME="htoc219">18.3.3</A>��Arrays</H3><P>Arrays of integers and pointers are represented like tuples,
392
that is, as pointers to blocks tagged�0. They are accessed with the
393
<TT>Field</TT> macro for reading and the <TT>modify</TT> function for writing.</P><P>Arrays of floating-point numbers (type <TT>float array</TT>)
578
394
have a special, unboxed, more efficient representation.
579
395
These arrays are represented by pointers to blocks with tag
580
396
<TT>Double_array_tag</TT>. They should be accessed with the <TT>Double_field</TT>
581
and <TT>Store_double_field</TT> macros.<BR>
582
<BR>
583
584
<H3 CLASS="subsection"><A NAME="htoc220">18.3.4</A> Concrete types</H3>
585
Constructed terms are represented either by unboxed integers (for
397
and <TT>Store_double_field</TT> macros.</P><H3 CLASS="subsection"><A NAME="htoc220">18.3.4</A>��Concrete types</H3><P>Constructed terms are represented either by unboxed integers (for
586
398
constant constructors) or by blocks whose tag encode the constructor
587
399
(for non-constant constructors). The constant constructors and the
588
400
non-constant constructors for a given concrete type are numbered
592
404
constructors declared with a <I>n</I>-tuple as argument are represented by
593
405
a block of size <I>n</I>, tagged with the constructor number; the <I>n</I>
594
406
fields contain the components of its tuple argument. Other
595
non-constant constructors are represented by a block of size 1, tagged
596
with the constructor number; the field 0 contains the value of the
597
constructor argument. Example:<BR>
598
<BR>
599
<DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
600
<TR><TD ALIGN=center NOWRAP><B>Constructed term</B></TD>
601
<TD ALIGN=center NOWRAP><B>Representation</B></TD>
602
</TR>
407
non-constant constructors are represented by a block of size�1, tagged
408
with the constructor number; the field�0 contains the value of the
409
constructor argument. Example:</P><DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%"><TR><TD ALIGN=center NOWRAP><B>Constructed term</B></TD><TD ALIGN=center NOWRAP><B>Representation</B></TD></TR>
603
410
<TR><TD VALIGN=top ALIGN=left NOWRAP>
604
<TT>()</TT></TD>
605
<TD VALIGN=top ALIGN=left><TT>Val_int(0)</TT></TD>
606
</TR>
607
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>false</TT></TD>
608
<TD VALIGN=top ALIGN=left><TT>Val_int(0)</TT></TD>
609
</TR>
610
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>true</TT></TD>
611
<TD VALIGN=top ALIGN=left><TT>Val_int(1)</TT></TD>
612
</TR>
613
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>[]</TT></TD>
614
<TD VALIGN=top ALIGN=left><TT>Val_int(0)</TT></TD>
615
</TR>
616
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>h::t</TT></TD>
617
<TD VALIGN=top ALIGN=left>Block with size = 2 and tag = 0; first field
618
contains <TT>h</TT>, second field <TT>t</TT></TD>
619
</TR></TABLE></DIV><BR>
620
<BR>
621
As a convenience, <TT>caml/mlvalues.h</TT> defines the macros <TT>Val_unit</TT>,
622
<TT>Val_false</TT> and <TT>Val_true</TT> to refer to <TT>()</TT>, <TT>false</TT> and <TT>true</TT>.<BR>
623
<BR>
624
625
<H3 CLASS="subsection"><A NAME="htoc221">18.3.5</A> Objects</H3>
626
Objects are represented as blocks
627
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
628
with tag <TT>Object_tag</TT>.
629
</div>
630
The first
411
<TT>()</TT></TD><TD VALIGN=top ALIGN=left><TT>Val_int(0)</TT></TD></TR>
412
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>false</TT></TD><TD VALIGN=top ALIGN=left><TT>Val_int(0)</TT></TD></TR>
413
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>true</TT></TD><TD VALIGN=top ALIGN=left><TT>Val_int(1)</TT></TD></TR>
414
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>[]</TT></TD><TD VALIGN=top ALIGN=left><TT>Val_int(0)</TT></TD></TR>
415
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>h::t</TT></TD><TD VALIGN=top ALIGN=left>Block with size = 2 and tag = 0; first field
416
contains <TT>h</TT>, second field <TT>t</TT></TD></TR>
417
</TABLE></DIV><P>As a convenience, <TT>caml/mlvalues.h</TT> defines the macros <TT>Val_unit</TT>,
418
<TT>Val_false</TT> and <TT>Val_true</TT> to refer to <TT>()</TT>, <TT>false</TT> and <TT>true</TT>.</P><H3 CLASS="subsection"><A NAME="htoc221">18.3.5</A>��Objects</H3><P>Objects are represented as blocks with tag <TT>Object_tag</TT>. The first
631
419
field of the block refers to the object class and associated method
632
suite, in a format that cannot easily be exploited from C.
633
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
634
The second
635
field contains a unique object ID, used for comparisons.
636
</div>
637
The remaining
420
suite, in a format that cannot easily be exploited from C. The second
421
field contains a unique object ID, used for comparisons. The remaining
638
422
fields of the object contain the values of the instance variables of
639
the object. Instance variables are stored in the order in which they
640
appear in the class definition (taking inherited classes into
641
account).<BR>
642
<BR>
643
One may extract a public method from an object using the C function
423
the object. It is unsafe to access directly instance variables, as the
424
type system provides no guaranteee about the instance variables
425
contained by an object.
426
</P><P>One may extract a public method from an object using the C function
644
427
<TT>caml_get_public_method</TT> (declared in <TT><caml/mlvalues.h></TT>.)
645
428
Since public method tags are hashed in the same way as variant tags,
646
429
and methods are functions taking self as first argument, if you want
647
430
to do the method call <TT>foo#bar</TT> from the C side, you should call:
648
<PRE CLASS="verbatim">
649
callback(caml_get_public_method(foo, hash_variant("bar")), foo);
650
</PRE>
651
652
<H3 CLASS="subsection"><A NAME="htoc222">18.3.6</A> Variants</H3>
653
Like constructed terms, values of variant types are represented either
431
</P><PRE CLASS="verbatim"> callback(caml_get_public_method(foo, hash_variant("bar")), foo);
432
</PRE><H3 CLASS="subsection"><A NAME="htoc222">18.3.6</A>��Variants</H3><P>Like constructed terms, values of variant types are represented either
654
433
as integers (for variants without arguments), or as blocks (for
655
434
variants with an argument). Unlike constructed terms, variant
656
435
constructors are not numbered starting from 0, but identified by a
657
436
hash value (a Caml integer), as computed by the C function
658
437
<TT>hash_variant</TT> (declared in <TT><caml/mlvalues.h></TT>):
659
438
the hash value for a variant constructor named, say, <TT>VConstr</TT>
660
is <TT>hash_variant("VConstr")</TT>.<BR>
661
<BR>
662
The variant value <TT>`VConstr</TT> is represented by
439
is <TT>hash_variant("VConstr")</TT>.</P><P>The variant value <TT>`VConstr</TT> is represented by
663
440
<TT>hash_variant("VConstr")</TT>. The variant value <TT>`VConstr(</TT><I>v</I><TT>)</TT> is
664
441
represented by a block of size 2 and tag 0, with field number 0
665
442
containing <TT>hash_variant("VConstr")</TT> and field number 1 containing
666
<I>v</I>.<BR>
667
<BR>
668
Unlike constructed values, variant values taking several arguments are
443
<I>v</I>.</P><P>Unlike constructed values, variant values taking several arguments are
669
444
not flattened. That is, <TT>`VConstr(</TT><I>v</I><TT>, </TT><I>v'</I><TT>)</TT> is
670
445
represented by a block of size 2, whose field number 1 contains
671
446
the representation of the pair <TT>(</TT><I>v</I><TT>, </TT><I>v'</I><TT>)</TT>, rather than a
672
block of size 3 containing <I>v</I> and <I>v'</I> in fields 1 and 2.<BR>
673
<BR>
674
675
<H2 CLASS="section"><A NAME="htoc223">18.4</A> Operations on values</H2>
676
677
678
<H3 CLASS="subsection"><A NAME="htoc224">18.4.1</A> Kind tests</H3>
679
<UL CLASS="itemize"><LI CLASS="li-itemize">
447
block of size 3 containing <I>v</I> and <I>v'</I> in fields 1 and 2.</P><H2 CLASS="section"><A NAME="htoc223">18.4</A>��Operations on values</H2><H3 CLASS="subsection"><A NAME="htoc224">18.4.1</A>��Kind tests</H3><UL CLASS="itemize"><LI CLASS="li-itemize">
680
448
<TT>Is_long(</TT><I>v</I><TT>)</TT> is true if value <I>v</I> is an immediate integer,
681
449
false otherwise
682
<LI CLASS="li-itemize"><TT>Is_block(</TT><I>v</I><TT>)</TT> is true if value <I>v</I> is a pointer to a block,
450
</LI><LI CLASS="li-itemize"><TT>Is_block(</TT><I>v</I><TT>)</TT> is true if value <I>v</I> is a pointer to a block,
683
451
and false if it is an immediate integer.
684
</UL>
685
686
<H3 CLASS="subsection"><A NAME="htoc225">18.4.2</A> Operations on integers</H3>
687
<UL CLASS="itemize"><LI CLASS="li-itemize">
452
</LI></UL><H3 CLASS="subsection"><A NAME="htoc225">18.4.2</A>��Operations on integers</H3><UL CLASS="itemize"><LI CLASS="li-itemize">
688
453
<TT>Val_long(</TT><I>l</I><TT>)</TT> returns the value encoding the <TT>long int</TT> <I>l</I>.
689
<LI CLASS="li-itemize"><TT>Long_val(</TT><I>v</I><TT>)</TT> returns the <TT>long int</TT> encoded in value <I>v</I>.
690
<LI CLASS="li-itemize"><TT>Val_int(</TT><I>i</I><TT>)</TT> returns the value encoding the <TT>int</TT> <I>i</I>.
691
<LI CLASS="li-itemize"><TT>Int_val(</TT><I>v</I><TT>)</TT> returns the <TT>int</TT> encoded in value <I>v</I>.
692
<LI CLASS="li-itemize"><TT>Val_bool(</TT><I>x</I><TT>)</TT> returns the Caml boolean representing the
454
</LI><LI CLASS="li-itemize"><TT>Long_val(</TT><I>v</I><TT>)</TT> returns the <TT>long int</TT> encoded in value <I>v</I>.
455
</LI><LI CLASS="li-itemize"><TT>Val_int(</TT><I>i</I><TT>)</TT> returns the value encoding the <TT>int</TT> <I>i</I>.
456
</LI><LI CLASS="li-itemize"><TT>Int_val(</TT><I>v</I><TT>)</TT> returns the <TT>int</TT> encoded in value <I>v</I>.
457
</LI><LI CLASS="li-itemize"><TT>Val_bool(</TT><I>x</I><TT>)</TT> returns the Caml boolean representing the
693
458
truth value of the C integer <I>x</I>.
694
<LI CLASS="li-itemize"><TT>Bool_val(</TT><I>v</I><TT>)</TT> returns 0 if <I>v</I> is the Caml boolean
459
</LI><LI CLASS="li-itemize"><TT>Bool_val(</TT><I>v</I><TT>)</TT> returns 0 if <I>v</I> is the Caml boolean
695
460
<TT>false</TT>, 1 if <I>v</I> is <TT>true</TT>.
696
<LI CLASS="li-itemize"><TT>Val_true</TT>, <TT>Val_false</TT> represent the Caml booleans <TT>true</TT> and <TT>false</TT>.
697
</UL>
698
699
<H3 CLASS="subsection"><A NAME="htoc226">18.4.3</A> Accessing blocks</H3>
700
<UL CLASS="itemize"><LI CLASS="li-itemize">
461
</LI><LI CLASS="li-itemize"><TT>Val_true</TT>, <TT>Val_false</TT> represent the Caml booleans <TT>true</TT> and <TT>false</TT>.
462
</LI></UL><H3 CLASS="subsection"><A NAME="htoc226">18.4.3</A>��Accessing blocks</H3><UL CLASS="itemize"><LI CLASS="li-itemize">
701
463
<TT>Wosize_val(</TT><I>v</I><TT>)</TT> returns the size of the block <I>v</I>, in words,
702
464
excluding the header.
703
<LI CLASS="li-itemize"><TT>Tag_val(</TT><I>v</I><TT>)</TT> returns the tag of the block <I>v</I>.
704
<LI CLASS="li-itemize"><TT>Field(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns the value contained in the
465
</LI><LI CLASS="li-itemize"><TT>Tag_val(</TT><I>v</I><TT>)</TT> returns the tag of the block <I>v</I>.
466
</LI><LI CLASS="li-itemize"><TT>Field(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns the value contained in the
705
467
<I>n</I><FONT SIZE=2><SUP>th</SUP></FONT> field of the structured block <I>v</I>. Fields are numbered from 0 to
706
<TT>Wosize_val</TT>(<I>v</I>)−1.
707
<LI CLASS="li-itemize"><TT>Store_field(</TT><I>b</I><TT>, </TT><I>n</I><TT>, </TT><I>v</I><TT>)</TT> stores the value
468
<TT>Wosize_val</TT>(<I>v</I>)−1.
469
</LI><LI CLASS="li-itemize"><TT>Store_field(</TT><I>b</I><TT>, </TT><I>n</I><TT>, </TT><I>v</I><TT>)</TT> stores the value
708
470
<I>v</I> in the field number <I>n</I> of value <I>b</I>, which must be a
709
471
structured block.
710
<LI CLASS="li-itemize"><TT>Code_val(</TT><I>v</I><TT>)</TT> returns the code part of the closure <I>v</I>.
711
<LI CLASS="li-itemize"><TT>string_length(</TT><I>v</I><TT>)</TT> returns the length (number of characters)
472
</LI><LI CLASS="li-itemize"><TT>Code_val(</TT><I>v</I><TT>)</TT> returns the code part of the closure <I>v</I>.
473
</LI><LI CLASS="li-itemize"><TT>string_length(</TT><I>v</I><TT>)</TT> returns the length (number of characters)
712
474
of the string <I>v</I>.
713
<LI CLASS="li-itemize"><TT>Byte(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns the <I>n</I><FONT SIZE=2><SUP>th</SUP></FONT> character of the string
475
</LI><LI CLASS="li-itemize"><TT>Byte(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns the <I>n</I><FONT SIZE=2><SUP>th</SUP></FONT> character of the string
714
476
<I>v</I>, with type <TT>char</TT>. Characters are numbered from 0 to
715
<TT>string_length</TT>(<I>v</I>)−1.
716
<LI CLASS="li-itemize"><TT>Byte_u(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns the <I>n</I><FONT SIZE=2><SUP>th</SUP></FONT> character of the string
477
<TT>string_length</TT>(<I>v</I>)−1.
478
</LI><LI CLASS="li-itemize"><TT>Byte_u(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns the <I>n</I><FONT SIZE=2><SUP>th</SUP></FONT> character of the string
717
479
<I>v</I>, with type <TT>unsigned char</TT>. Characters are numbered from 0 to
718
<TT>string_length</TT>(<I>v</I>)−1.
719
<LI CLASS="li-itemize"><TT>String_val(</TT><I>v</I><TT>)</TT> returns a pointer to the first byte of the string
480
<TT>string_length</TT>(<I>v</I>)−1.
481
</LI><LI CLASS="li-itemize"><TT>String_val(</TT><I>v</I><TT>)</TT> returns a pointer to the first byte of the string
720
482
<I>v</I>, with type <TT>char *</TT>. This pointer is a valid C string: there is a
721
483
null character after the last character in the string. However, Caml
722
484
strings can contain embedded null characters, that will confuse
723
485
the usual C functions over strings.
724
<LI CLASS="li-itemize"><TT>Double_val(</TT><I>v</I><TT>)</TT> returns the floating-point number contained in
486
</LI><LI CLASS="li-itemize"><TT>Double_val(</TT><I>v</I><TT>)</TT> returns the floating-point number contained in
725
487
value <I>v</I>, with type <TT>double</TT>.
726
<LI CLASS="li-itemize"><TT>Double_field(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns
488
</LI><LI CLASS="li-itemize"><TT>Double_field(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> returns
727
489
the <I>n</I><FONT SIZE=2><SUP>th</SUP></FONT> element of the array of floating-point numbers <I>v</I> (a
728
490
block tagged <TT>Double_array_tag</TT>).
729
<LI CLASS="li-itemize"><TT>Store_double_field(</TT><I>v</I><TT>, </TT><I>n</I><TT>, </TT><I>d</I><TT>)</TT> stores the double precision floating-point number <I>d</I>
491
</LI><LI CLASS="li-itemize"><TT>Store_double_field(</TT><I>v</I><TT>, </TT><I>n</I><TT>, </TT><I>d</I><TT>)</TT> stores the double precision floating-point number <I>d</I>
730
492
in the <I>n</I><FONT SIZE=2><SUP>th</SUP></FONT> element of the array of floating-point numbers <I>v</I>.
731
<LI CLASS="li-itemize"><TT>Data_custom_val(</TT><I>v</I><TT>)</TT> returns a pointer to the data part
493
</LI><LI CLASS="li-itemize"><TT>Data_custom_val(</TT><I>v</I><TT>)</TT> returns a pointer to the data part
732
494
of the custom block <I>v</I>. This pointer has type <TT>void *</TT> and must
733
495
be cast to the type of the data contained in the custom block.
734
<LI CLASS="li-itemize"><TT>Int32_val(</TT><I>v</I><TT>)</TT> returns the 32-bit integer contained
496
</LI><LI CLASS="li-itemize"><TT>Int32_val(</TT><I>v</I><TT>)</TT> returns the 32-bit integer contained
735
497
in the <TT>int32</TT> <I>v</I>.
736
<LI CLASS="li-itemize"><TT>Int64_val(</TT><I>v</I><TT>)</TT> returns the 64-bit integer contained
498
</LI><LI CLASS="li-itemize"><TT>Int64_val(</TT><I>v</I><TT>)</TT> returns the 64-bit integer contained
737
499
in the <TT>int64</TT> <I>v</I>.
738
<LI CLASS="li-itemize"><TT>Nativeint_val(</TT><I>v</I><TT>)</TT> returns the long integer contained
500
</LI><LI CLASS="li-itemize"><TT>Nativeint_val(</TT><I>v</I><TT>)</TT> returns the long integer contained
739
501
in the <TT>nativeint</TT> <I>v</I>.
740
</UL>
502
</LI></UL><P>
741
503
The expressions <TT>Field(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT>,
742
504
<TT>Byte(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> and
743
505
<TT>Byte_u(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT>
745
507
in-place modification of value <I>v</I>.
746
508
Assigning directly to <TT>Field(</TT><I>v</I><TT>, </TT><I>n</I><TT>)</TT> must
747
509
be done with care to avoid confusing the garbage collector (see
748
below).<BR>
749
<BR>
750
751
<H3 CLASS="subsection"><A NAME="htoc227">18.4.4</A> Allocating blocks</H3>
752
753
<H4 CLASS="subsubsection">Simple interface</H4>
754
<UL CLASS="itemize"><LI CLASS="li-itemize">
755
<TT>Atom(</TT><I>t</I><TT>)</TT> returns an “atom” (zero-sized block) with tag <I>t</I>.
510
below).</P><H3 CLASS="subsection"><A NAME="htoc227">18.4.4</A>��Allocating blocks</H3><H4 CLASS="subsubsection">Simple interface</H4><UL CLASS="itemize"><LI CLASS="li-itemize">
511
<TT>Atom(</TT><I>t</I><TT>)</TT> returns an “atom” (zero-sized block) with tag <I>t</I>.
756
512
Zero-sized blocks are preallocated outside of the heap. It is
757
513
incorrect to try and allocate a zero-sized block using the functions below.
758
514
For instance, <TT>Atom(0)</TT> represents the empty array.
759
<LI CLASS="li-itemize"><TT>caml_alloc(</TT><I>n</I><TT>, </TT><I>t</I><TT>)</TT> returns a fresh block of size <I>n</I>
515
</LI><LI CLASS="li-itemize"><TT>caml_alloc(</TT><I>n</I><TT>, </TT><I>t</I><TT>)</TT> returns a fresh block of size <I>n</I>
760
516
with tag <I>t</I>. If <I>t</I> is less than <TT>No_scan_tag</TT>, then the
761
517
fields of the block are initialized with a valid value in order to
762
518
satisfy the GC constraints.
763
<LI CLASS="li-itemize"><TT>caml_alloc_tuple(</TT><I>n</I><TT>)</TT> returns a fresh block of size
519
</LI><LI CLASS="li-itemize"><TT>caml_alloc_tuple(</TT><I>n</I><TT>)</TT> returns a fresh block of size
764
520
<I>n</I> words, with tag 0.
765
<LI CLASS="li-itemize"><TT>caml_alloc_string(</TT><I>n</I><TT>)</TT> returns a string value of length <I>n</I> characters.
521
</LI><LI CLASS="li-itemize"><TT>caml_alloc_string(</TT><I>n</I><TT>)</TT> returns a string value of length <I>n</I> characters.
766
522
The string initially contains garbage.
767
<LI CLASS="li-itemize"><TT>caml_copy_string(</TT><I>s</I><TT>)</TT> returns a string value containing a copy of
523
</LI><LI CLASS="li-itemize"><TT>caml_copy_string(</TT><I>s</I><TT>)</TT> returns a string value containing a copy of
768
524
the null-terminated C string <I>s</I> (a <TT>char *</TT>).
769
<LI CLASS="li-itemize"><TT>caml_copy_double(</TT><I>d</I><TT>)</TT> returns a floating-point value initialized
525
</LI><LI CLASS="li-itemize"><TT>caml_copy_double(</TT><I>d</I><TT>)</TT> returns a floating-point value initialized
770
526
with the <TT>double</TT> <I>d</I>.
771
<LI CLASS="li-itemize"><TT>caml_copy_int32(</TT><I>i</I><TT>)</TT>, <TT>copy_int64(</TT><I>i</I><TT>)</TT> and
527
</LI><LI CLASS="li-itemize"><TT>caml_copy_int32(</TT><I>i</I><TT>)</TT>, <TT>copy_int64(</TT><I>i</I><TT>)</TT> and
772
528
<TT>caml_copy_nativeint(</TT><I>i</I><TT>)</TT> return a value of Caml type <TT>int32</TT>,
773
529
<TT>int64</TT> and <TT>nativeint</TT>, respectively, initialized with the integer
774
530
<I>i</I>.
775
<LI CLASS="li-itemize"><TT>caml_alloc_array(</TT><I>f</I><TT>, </TT><I>a</I><TT>)</TT> allocates an array of values, calling
531
</LI><LI CLASS="li-itemize"><TT>caml_alloc_array(</TT><I>f</I><TT>, </TT><I>a</I><TT>)</TT> allocates an array of values, calling
776
532
function <I>f</I> over each element of the input array <I>a</I> to transform it
777
533
into a value. The array <I>a</I> is an array of pointers terminated by the
778
534
null pointer. The function <I>f</I> receives each pointer as argument, and
780
536
<TT>alloc_array(</TT><I>f</I><TT>, </TT><I>a</I><TT>)</TT> is filled with the values returned by the
781
537
successive calls to <I>f</I>. (This function must not be used to build
782
538
an array of floating-point numbers.)
783
<LI CLASS="li-itemize"><TT>caml_copy_string_array(</TT><I>p</I><TT>)</TT> allocates an array of strings, copied from
539
</LI><LI CLASS="li-itemize"><TT>caml_copy_string_array(</TT><I>p</I><TT>)</TT> allocates an array of strings, copied from
784
540
the pointer to a string array <I>p</I> (a <CODE>char **</CODE>). <I>p</I> must
785
541
be NULL-terminated.
786
</UL>
787
788
<H4 CLASS="subsubsection">Low-level interface</H4>
789
The following functions are slightly more efficient than <TT>caml_alloc</TT>, but
790
also much more difficult to use.<BR>
791
<BR>
792
From the standpoint of the allocation functions, blocks are divided
542
</LI></UL><H4 CLASS="subsubsection">Low-level interface</H4><P>The following functions are slightly more efficient than <TT>caml_alloc</TT>, but
543
also much more difficult to use.</P><P>From the standpoint of the allocation functions, blocks are divided
793
544
according to their size as zero-sized blocks, small blocks (with size
794
545
less than or equal to <CODE>Max_young_wosize</CODE>), and large blocks (with
795
546
size greater than <CODE>Max_young_wosize</CODE>). The constant
797
548
is guaranteed to be at least 64 (words), so that any block with
798
549
constant size less than or equal to 64 can be assumed to be small. For
799
550
blocks whose size is computed at run-time, the size must be compared
800
against <CODE>Max_young_wosize</CODE> to determine the correct allocation procedure.
801
<UL CLASS="itemize"><LI CLASS="li-itemize">
551
against <CODE>Max_young_wosize</CODE> to determine the correct allocation procedure.</P><UL CLASS="itemize"><LI CLASS="li-itemize">
802
552
<TT>caml_alloc_small(</TT><I>n</I><TT>, </TT><I>t</I><TT>)</TT> returns a fresh small block of size
803
<I>n</I> ≤ <TT>Max_young_wosize</TT> words, with tag <I>t</I>.
553
<I>n</I> ≤ <TT>Max_young_wosize</TT> words, with tag <I>t</I>.
804
554
If this block is a structured block (i.e. if <I>t</I> < <TT>No_scan_tag</TT>), then
805
555
the fields of the block (initially containing garbage) must be initialized
806
556
with legal values (using direct assignment to the fields of the block)
807
557
before the next allocation.
808
<LI CLASS="li-itemize"><TT>caml_alloc_shr(</TT><I>n</I><TT>, </TT><I>t</I><TT>)</TT> returns a fresh block of size
558
</LI><LI CLASS="li-itemize"><TT>caml_alloc_shr(</TT><I>n</I><TT>, </TT><I>t</I><TT>)</TT> returns a fresh block of size
809
559
<I>n</I>, with tag <I>t</I>.
810
560
The size of the block can be greater than <CODE>Max_young_wosize</CODE>. (It
811
561
can also be smaller, but in this case it is more efficient to call
814
564
the fields of the block (initially containing garbage) must be initialized
815
565
with legal values (using the <TT>initialize</TT> function described below)
816
566
before the next allocation.
817
</UL>
818
819
<H3 CLASS="subsection"><A NAME="htoc228">18.4.5</A> Raising exceptions</H3> <A NAME="s:c-exceptions"></A>
820
Two functions are provided to raise two standard exceptions:
821
<UL CLASS="itemize"><LI CLASS="li-itemize">
567
</LI></UL><H3 CLASS="subsection"><A NAME="htoc228">18.4.5</A>��Raising exceptions</H3><P> <A NAME="s:c-exceptions"></A></P><P>Two functions are provided to raise two standard exceptions:
568
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
822
569
<TT>caml_failwith(</TT><I>s</I><TT>)</TT>, where <I>s</I> is a null-terminated C string (with
823
570
type <CODE>char *</CODE>), raises exception <TT>Failure</TT> with argument <I>s</I>.
824
<LI CLASS="li-itemize"><TT>caml_invalid_argument(</TT><I>s</I><TT>)</TT>, where <I>s</I> is a null-terminated C
571
</LI><LI CLASS="li-itemize"><TT>caml_invalid_argument(</TT><I>s</I><TT>)</TT>, where <I>s</I> is a null-terminated C
825
572
string (with type <CODE>char *</CODE>), raises exception <TT>Invalid_argument</TT>
826
573
with argument <I>s</I>.
827
</UL>
828
Raising arbitrary exceptions from C is more delicate: the
574
</LI></UL><P>Raising arbitrary exceptions from C is more delicate: the
829
575
exception identifier is dynamically allocated by the Caml program, and
830
576
therefore must be communicated to the C function using the
831
registration facility described below in section <A HREF="#s:register-exn">18.7.3</A>.
577
registration facility described below in section�<A HREF="#s:register-exn">18.7.3</A>.
832
578
Once the exception identifier is recovered in C, the following
833
579
functions actually raise the exception:
834
<UL CLASS="itemize"><LI CLASS="li-itemize">
580
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
835
581
<TT>caml_raise_constant(</TT><I>id</I><TT>)</TT> raises the exception <I>id</I> with
836
582
no argument;
837
<LI CLASS="li-itemize"><TT>caml_raise_with_arg(</TT><I>id</I><TT>, </TT><I>v</I><TT>)</TT> raises the exception
583
</LI><LI CLASS="li-itemize"><TT>caml_raise_with_arg(</TT><I>id</I><TT>, </TT><I>v</I><TT>)</TT> raises the exception
838
584
<I>id</I> with the Caml value <I>v</I> as argument;
839
<LI CLASS="li-itemize"><TT>caml_raise_with_string(</TT><I>id</I><TT>, </TT><I>s</I><TT>)</TT>, where <I>s</I> is a
585
</LI><LI CLASS="li-itemize"><TT>caml_raise_with_string(</TT><I>id</I><TT>, </TT><I>s</I><TT>)</TT>, where <I>s</I> is a
840
586
null-terminated C string, raises the exception <I>id</I> with a copy of
841
587
the C string <I>s</I> as argument.
842
</UL>
843
844
<H2 CLASS="section"><A NAME="htoc229">18.5</A> Living in harmony with the garbage collector</H2>
845
846
Unused blocks in the heap are automatically reclaimed by the garbage
588
</LI></UL><H2 CLASS="section"><A NAME="htoc229">18.5</A>��Living in harmony with the garbage collector</H2><P>Unused blocks in the heap are automatically reclaimed by the garbage
847
589
collector. This requires some cooperation from C code that
848
manipulates heap-allocated blocks.<BR>
849
<BR>
850
851
<H3 CLASS="subsection"><A NAME="htoc230">18.5.1</A> Simple interface</H3>
852
All the macros described in this section are declared in the
853
<TT>memory.h</TT> header file.<BR>
854
<BR>
855
<DIV CLASS="flushleft"><B>Rule 1</B> <EM>
590
manipulates heap-allocated blocks.</P><H3 CLASS="subsection"><A NAME="htoc230">18.5.1</A>��Simple interface</H3><P>All the macros described in this section are declared in the
591
<TT>memory.h</TT> header file.</P><DIV CLASS="theorem"><B>Rule�1</B>��<EM>
856
592
A function that has parameters or local variables of type <TT>value</TT> must
857
593
begin with a call to one of the <TT>CAMLparam</TT> macros and return with
858
<TT>CAMLreturn</TT> or <TT>CAMLreturn0</TT>.
859
</EM></DIV><BR>
860
<BR>
861
There are six <TT>CAMLparam</TT> macros: <TT>CAMLparam0</TT> to <TT>CAMLparam5</TT>, which
594
<TT>CAMLreturn</TT>, <TT>CAMLreturn0</TT>, or <TT>CAMLreturnT</TT>.
595
</EM></DIV><P>There are six <TT>CAMLparam</TT> macros: <TT>CAMLparam0</TT> to <TT>CAMLparam5</TT>, which
862
596
take zero to five arguments respectively. If your function has fewer
863
597
than 5 parameters of type <TT>value</TT>, use the corresponding macros
864
598
with these parameters as arguments. If your function has more than 5
865
599
parameters of type <TT>value</TT>, use <TT>CAMLparam5</TT> with five of these
866
600
parameters, and use one or more calls to the <TT>CAMLxparam</TT> macros for
867
the remaining parameters (<TT>CAMLxparam1</TT> to <TT>CAMLxparam5</TT>).<BR>
868
<BR>
869
The macros <TT>CAMLreturn</TT> and <TT>CAMLreturn0</TT> are used to replace the C
601
the remaining parameters (<TT>CAMLxparam1</TT> to <TT>CAMLxparam5</TT>).</P><P>The macros <TT>CAMLreturn</TT>, <TT>CAMLreturn0</TT>, and <TT>CAMLreturnT</TT> are used to
602
replace the C
870
603
keyword <TT>return</TT>. Every occurence of <TT>return x</TT> must be replaced by
871
<TT>CAMLreturn (x)</TT>, every occurence of <TT>return</TT> without argument must be
604
<TT>CAMLreturn (x)</TT> if <TT>x</TT> has type <TT>value</TT>, or <TT>CAMLreturnT (t, x)</TT>
605
(where <TT>t</TT> is the type of <TT>x</TT>); every occurence of <TT>return</TT> without
606
argument must be
872
607
replaced by <TT>CAMLreturn0</TT>. If your C function is a procedure (i.e. if
873
608
it returns void), you must insert <TT>CAMLreturn0</TT> at the end (to replace
874
C's implicit <TT>return</TT>).<BR>
875
<BR>
876
877
<H5 CLASS="paragraph">Note:</H5> some C compilers give bogus warnings about unused
609
C's implicit <TT>return</TT>).</P><H5 CLASS="paragraph">Note:</H5><P> some C compilers give bogus warnings about unused
878
610
variables <TT>caml__dummy_xxx</TT> at each use of <TT>CAMLparam</TT> and
879
<TT>CAMLlocal</TT>. You should ignore them.<BR>
880
<BR>
881
<BR>
882
<BR>
883
<BR>
884
Example:
885
<PRE CLASS="verbatim">
886
void foo (value v1, value v2, value v3)
611
<TT>CAMLlocal</TT>. You should ignore them.</P><P><BR>
612
</P><P>Example:
613
</P><PRE CLASS="verbatim">void foo (value v1, value v2, value v3)
887
614
{
888
615
CAMLparam3 (v1, v2, v3);
889
616
...
890
617
CAMLreturn0;
891
618
}
892
</PRE>
893
894
<H5 CLASS="paragraph">Note:</H5> if your function is a primitive with more than 5 arguments
619
</PRE><H5 CLASS="paragraph">Note:</H5><P> if your function is a primitive with more than 5 arguments
895
620
for use with the byte-code runtime, its arguments are not <TT>value</TT>s and
896
must not be declared (they have types <TT>value *</TT> and <TT>int</TT>).<BR>
897
<BR>
898
<DIV CLASS="flushleft"><B>Rule 2</B> <EM>
621
must not be declared (they have types <TT>value *</TT> and <TT>int</TT>).</P><DIV CLASS="theorem"><B>Rule�2</B>��<EM>
899
622
Local variables of type <TT>value</TT> must be declared with one of the
900
623
<TT>CAMLlocal</TT> macros. Arrays of <TT>value</TT>s are declared with
901
<TT>CAMLlocalN</TT>.
902
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
903
These macros must be used at the beginning of the
624
<TT>CAMLlocalN</TT>. These macros must be used at the beginning of the
904
625
function, not in a nested block.
905
</div>
906
</EM></DIV><BR>
907
<BR>
908
The macros <TT>CAMLlocal1</TT> to <TT>CAMLlocal5</TT> declare and initialize one to
626
</EM></DIV><P>The macros <TT>CAMLlocal1</TT> to <TT>CAMLlocal5</TT> declare and initialize one to
909
627
five local variables of type <TT>value</TT>. The variable names are given as
910
628
arguments to the macros. <TT>CAMLlocalN(</TT><I>x</I><TT>, </TT><I>n</I><TT>)</TT> declares
911
629
and initializes a local variable of type <TT>value [</TT><I>n</I><TT>]</TT>. You can
912
630
use several calls to these macros if you have more than 5 local
913
variables.
914
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
915
<STRIKE>You can also use them in nested C blocks within the
916
function.</STRIKE> (deleted)
917
</div>
918
<BR>
919
<BR>
920
Example:
921
<PRE CLASS="verbatim">
922
value bar (value v1, value v2, value v3)
631
variables.</P><P>Example:
632
</P><PRE CLASS="verbatim">value bar (value v1, value v2, value v3)
923
633
{
924
634
CAMLparam3 (v1, v2, v3);
925
635
CAMLlocal1 (result);
927
637
...
928
638
CAMLreturn (result);
929
639
}
930
</PRE><BR>
931
<BR>
932
<DIV CLASS="flushleft"><B>Rule 3</B> <EM>
640
</PRE><DIV CLASS="theorem"><B>Rule�3</B>��<EM>
933
641
Assignments to the fields of structured blocks must be done with the
934
642
<TT>Store_field</TT> macro (for normal blocks) or <TT>Store_double_field</TT> macro
935
643
(for arrays and records of floating-point numbers). Other assignments
936
644
must not use <TT>Store_field</TT> nor <TT>Store_double_field</TT>.
937
</EM></DIV><BR>
938
<BR>
939
<TT>Store_field (</TT><I>b</I><TT>, </TT><I>n</I><TT>, </TT><I>v</I><TT>)</TT> stores the value
645
</EM></DIV><P><TT>Store_field (</TT><I>b</I><TT>, </TT><I>n</I><TT>, </TT><I>v</I><TT>)</TT> stores the value
940
646
<I>v</I> in the field number <I>n</I> of value <I>b</I>, which must be a
941
block (i.e. <TT>Is_block(</TT><I>b</I><TT>)</TT> must be true).<BR>
942
<BR>
943
Example:
944
<PRE CLASS="verbatim">
945
value bar (value v1, value v2, value v3)
647
block (i.e. <TT>Is_block(</TT><I>b</I><TT>)</TT> must be true).</P><P>Example:
648
</P><PRE CLASS="verbatim">value bar (value v1, value v2, value v3)
946
649
{
947
650
CAMLparam3 (v1, v2, v3);
948
651
CAMLlocal1 (result);
952
655
Store_field (result, 2, v3);
953
656
CAMLreturn (result);
954
657
}
955
</PRE>
956
957
<H5 CLASS="paragraph">Warning:</H5> The first argument of <TT>Store_field</TT> and
658
</PRE><H5 CLASS="paragraph">Warning:</H5><P> The first argument of <TT>Store_field</TT> and
958
659
<TT>Store_double_field</TT> must be a variable declared by <TT>CAMLparam*</TT> or
959
660
a parameter declared by <TT>CAMLlocal*</TT> to ensure that a garbage
960
661
collection triggered by the evaluation of the other arguments will not
961
invalidate the first argument after it is computed.<BR>
962
<BR>
963
<DIV CLASS="flushleft"><B>Rule 4</B> <EM> Global variables containing values must be registered
662
invalidate the first argument after it is computed.</P><DIV CLASS="theorem"><B>Rule�4</B>��<EM> Global variables containing values must be registered
964
663
with the garbage collector using the <TT>register_global_root</TT> function.
965
</EM></DIV><BR>
966
<BR>
967
Registration of a global variable <TT>v</TT> is achieved by calling
664
</EM></DIV><P>Registration of a global variable <TT>v</TT> is achieved by calling
968
665
<TT>caml_register_global_root(&v)</TT> just before a valid value is stored in <TT>v</TT>
969
for the first time. <BR>
970
<BR>
971
A registered global variable <TT>v</TT> can be un-registered by calling
972
<TT>caml_remove_global_root(&v)</TT>.<BR>
973
<BR>
974
<B>Note:</B> The <TT>CAML</TT> macros use identifiers (local variables, type
666
for the first time. </P><P>A registered global variable <TT>v</TT> can be un-registered by calling
667
<TT>caml_remove_global_root(&v)</TT>.</P><P><B>Note:</B> The <TT>CAML</TT> macros use identifiers (local variables, type
975
668
identifiers, structure tags) that start with <TT>caml__</TT>. Do not use any
976
identifier starting with <TT>caml__</TT> in your programs.<BR>
977
<BR>
978
979
<H3 CLASS="subsection"><A NAME="htoc231">18.5.2</A> Low-level interface</H3>
980
We now give the GC rules corresponding to the low-level allocation
669
identifier starting with <TT>caml__</TT> in your programs.</P><H3 CLASS="subsection"><A NAME="htoc231">18.5.2</A>��Low-level interface</H3><P>We now give the GC rules corresponding to the low-level allocation
981
670
functions <TT>caml_alloc_small</TT> and <TT>caml_alloc_shr</TT>. You can ignore those rules
982
if you stick to the simplified allocation function <TT>caml_alloc</TT>.<BR>
983
<BR>
984
<DIV CLASS="flushleft"><B>Rule 5</B> <EM> After a structured block (a block with tag less than
671
if you stick to the simplified allocation function <TT>caml_alloc</TT>.</P><DIV CLASS="theorem"><B>Rule�5</B>��<EM> After a structured block (a block with tag less than
985
672
<TT>No_scan_tag</TT>) is allocated with the low-level functions, all fields
986
673
of this block must be filled with well-formed values before the next
987
674
allocation operation. If the block has been allocated with
995
682
</EM><PRE><EM>
996
683
caml_initialize(&Field(<I>v</I>, <I>n</I>), <I>v<SUB>n</SUB></I>);
997
684
</EM></PRE>
998
</DIV><BR>
999
<BR>
1000
The next allocation can trigger a garbage collection. The garbage
685
</DIV><P>The next allocation can trigger a garbage collection. The garbage
1001
686
collector assumes that all structured blocks contain well-formed
1002
687
values. Newly created blocks contain random data, which generally do
1003
not represent well-formed values.<BR>
1004
<BR>
1005
If you really need to allocate before the fields can receive their
688
not represent well-formed values.</P><P>If you really need to allocate before the fields can receive their
1006
689
final value, first initialize with a constant value (e.g.
1007
690
<TT>Val_unit</TT>), then allocate, then modify the fields with the correct
1008
value (see rule 6).<BR>
1009
<BR>
1010
<DIV CLASS="flushleft"><B>Rule 6</B> <EM> Direct assignment to a field of a block, as in
691
value (see rule�6).</P><DIV CLASS="theorem"><B>Rule�6</B>��<EM> Direct assignment to a field of a block, as in
1011
692
</EM><PRE><EM>
1012
693
Field(<I>v</I>, <I>n</I>) = <I>w</I>;
1013
694
</EM></PRE><EM>
1024
705
</EM><PRE><EM>
1025
706
caml_modify(&Field(<I>v</I>, <I>n</I>), <I>w</I>);
1026
707
</EM></PRE>
1027
</DIV><BR>
1028
<BR>
1029
To illustrate the rules above, here is a C function that builds and
708
</DIV><P>To illustrate the rules above, here is a C function that builds and
1030
709
returns a list containing the two integers given as parameters.
1031
710
First, we write it using the simplified allocation functions:
1032
<PRE CLASS="verbatim">
1033
value alloc_list_int(int i1, int i2)
711
</P><PRE CLASS="verbatim">value alloc_list_int(int i1, int i2)
1034
712
{
1035
713
CAMLparam0 ();
1036
714
CAMLlocal2 (result, r);
1043
721
Store_field(result, 1, r); /* cdr = the first cons cell */
1044
722
CAMLreturn (result);
1045
723
}
1046
</PRE>Here, the registering of <TT>result</TT> is not strictly needed, because no
724
</PRE><P>Here, the registering of <TT>result</TT> is not strictly needed, because no
1047
725
allocation takes place after it gets its value, but it's easier and
1048
safer to simply register all the local variables that have type <TT>value</TT>.<BR>
1049
<BR>
1050
Here is the same function written using the low-level allocation
726
safer to simply register all the local variables that have type <TT>value</TT>.</P><P>Here is the same function written using the low-level allocation
1051
727
functions. We notice that the cons cells are small blocks and can be
1052
728
allocated with <TT>caml_alloc_small</TT>, and filled by direct assignments on
1053
729
their fields.
1054
<PRE CLASS="verbatim">
1055
value alloc_list_int(int i1, int i2)
730
</P><PRE CLASS="verbatim">value alloc_list_int(int i1, int i2)
1056
731
{
1057
732
CAMLparam0 ();
1058
733
CAMLlocal2 (result, r);
1065
740
Field(result, 1) = r; /* cdr = the first cons cell */
1066
741
CAMLreturn (result);
1067
742
}
1068
</PRE>In the two examples above, the list is built bottom-up. Here is an
743
</PRE><P>In the two examples above, the list is built bottom-up. Here is an
1069
744
alternate way, that proceeds top-down. It is less efficient, but
1070
745
illustrates the use of <TT>modify</TT>.
1071
<PRE CLASS="verbatim">
1072
value alloc_list_int(int i1, int i2)
746
</P><PRE CLASS="verbatim">value alloc_list_int(int i1, int i2)
1073
747
{
1074
748
CAMLparam0 ();
1075
749
CAMLlocal2 (tail, r);
1083
757
caml_modify(&Field(r, 1), tail); /* cdr of the result = tail */
1084
758
CAMLreturn (r);
1085
759
}
1086
</PRE>It would be incorrect to perform
760
</PRE><P>It would be incorrect to perform
1087
761
<TT>Field(r, 1) = tail</TT> directly, because the allocation of <TT>tail</TT>
1088
has taken place since <TT>r</TT> was allocated.<BR>
1089
<BR>
1090
1091
<H2 CLASS="section"><A NAME="htoc232">18.6</A> A complete example</H2>
1092
1093
This section outlines how the functions from the Unix <TT>curses</TT> library
762
has taken place since <TT>r</TT> was allocated.</P><H2 CLASS="section"><A NAME="htoc232">18.6</A>��A complete example</H2><P>This section outlines how the functions from the Unix <TT>curses</TT> library
1094
763
can be made available to Objective Caml programs. First of all, here is
1095
764
the interface <TT>curses.mli</TT> that declares the <TT>curses</TT> primitives and
1096
765
data types:
1097
<PRE CLASS="verbatim">
1098
type window (* The type "window" remains abstract *)
766
</P><PRE CLASS="verbatim">type window (* The type "window" remains abstract *)
1099
767
external initscr: unit -> window = "curses_initscr"
1100
768
external endwin: unit -> unit = "curses_endwin"
1101
769
external refresh: unit -> unit = "curses_refresh"
1106
774
external addstr: string -> unit = "curses_addstr"
1107
775
external mvwaddstr: window -> int -> int -> string -> unit = "curses_mvwaddstr"
1108
776
(* lots more omitted *)
1109
</PRE>To compile this interface:
1110
<PRE CLASS="verbatim">
1111
ocamlc -c curses.mli
1112
</PRE>
1113
To implement these functions, we just have to provide the stub code;
777
</PRE><P>To compile this interface:
778
</P><PRE CLASS="verbatim"> ocamlc -c curses.mli
779
</PRE><P>To implement these functions, we just have to provide the stub code;
1114
780
the core functions are already implemented in the <TT>curses</TT> library.
1115
781
The stub code file, <TT>curses_stubs.c</TT>, looks like this:
1116
<PRE CLASS="verbatim">
1117
#include <curses.h>
1118
<span style="background-color:yellow; color:red">#include <caml/mlvalues.h>
782
</P><PRE CLASS="verbatim">#include <curses.h>
783
#include <caml/mlvalues.h>
1119
784
#include <caml/memory.h>
1120
785
#include <caml/alloc.h>
1121
786
#include <caml/custom.h>
1141
806
value v = alloc_custom(&curses_window_ops, sizeof(WINDOW *), 0, 1);
1142
807
Window_val(v) = w;
1143
808
return v;
1144
}</span>
809
}
1145
810
1146
811
value caml_curses_initscr(value unit)
1147
812
{
1148
813
CAMLparam1 (unit);
1149
CAMLreturn (<span style="background-color:yellow; color:red">alloc_window</span>(initscr()));
814
CAMLreturn (alloc_window(initscr()));
1150
815
}
1151
816
1152
<span style="background-color:yellow; color:red">value caml_curses_endwin(value unit)
817
value caml_curses_endwin(value unit)
1153
818
{
1154
819
CAMLparam1 (unit);
1155
820
endwin();
1161
826
CAMLparam1 (unit);
1162
827
refresh();
1163
828
CAMLreturn (Val_unit);
1164
}</span>
829
}
1165
830
1166
831
value caml_curses_wrefresh(value win)
1167
832
{
1168
833
CAMLparam1 (win);
1169
wrefresh(<span style="background-color:yellow; color:red">Window_val</span>(win));
834
wrefresh(Window_val(win));
1170
835
CAMLreturn (Val_unit);
1171
836
}
1172
837
1173
838
value caml_curses_newwin(value nlines, value ncols, value x0, value y0)
1174
839
{
1175
840
CAMLparam4 (nlines, ncols, x0, y0);
1176
CAMLreturn (<span style="background-color:yellow; color:red">alloc_window</span>(newwin(Int_val(nlines), Int_val(ncols),
841
CAMLreturn (alloc_window(newwin(Int_val(nlines), Int_val(ncols),
1177
842
Int_val(x0), Int_val(y0))));
1178
843
}
1179
844
1184
849
CAMLreturn (Val_unit);
1185
850
}
1186
851
1187
<span style="background-color:yellow; color:red">value caml_curses_mvwaddch(value win, value x, value y, value c)
852
value caml_curses_mvwaddch(value win, value x, value y, value c)
1188
853
{
1189
854
CAMLparam4 (win, x, y, c);
1190
855
mvwaddch(Window_val(win), Int_val(x), Int_val(y), Int_val(c));
1191
856
CAMLreturn (Val_unit);
1192
}</span>
857
}
1193
858
1194
859
value caml_curses_addstr(value s)
1195
860
{
1198
863
CAMLreturn (Val_unit);
1199
864
}
1200
865
1201
<span style="background-color:yellow; color:red">value caml_curses_mvwaddstr(value win, value x, value y, value s)
866
value caml_curses_mvwaddstr(value win, value x, value y, value s)
1202
867
{
1203
868
CAMLparam4 (win, x, y, s);
1204
869
mvwaddstr(Window_val(win), Int_val(x), Int_val(y), String_val(s));
1205
870
CAMLreturn (Val_unit);
1206
}</span>
871
}
1207
872
1208
873
/* This goes on for pages. */
1209
</PRE>
1210
The file <TT>curses_stubs.c</TT> can be compiled with:
1211
<PRE CLASS="verbatim">
1212
cc -c -I/usr/local/lib/ocaml curses.c
1213
</PRE>or, even simpler,
1214
<PRE CLASS="verbatim">
1215
ocamlc -c curses.c
1216
</PRE>(When passed a <TT>.c</TT> file, the <TT>ocamlc</TT> command simply calls the C
1217
compiler on that file, with the right <TT>-I</TT> option.)<BR>
1218
<BR>
1219
Now, here is a sample Caml program <TT>test.ml</TT> that uses the <TT>curses</TT>
874
</PRE><P>The file <TT>curses_stubs.c</TT> can be compiled with:
875
</P><PRE CLASS="verbatim"> cc -c -I/usr/local/lib/ocaml curses.c
876
</PRE><P>or, even simpler,
877
</P><PRE CLASS="verbatim"> ocamlc -c curses.c
878
</PRE><P>(When passed a <TT>.c</TT> file, the <TT>ocamlc</TT> command simply calls the C
879
compiler on that file, with the right <TT>-I</TT> option.)</P><P>Now, here is a sample Caml program <TT>test.ml</TT> that uses the <TT>curses</TT>
1220
880
module:
1221
<PRE CLASS="verbatim">
1222
open Curses
881
</P><PRE CLASS="verbatim">open Curses
1223
882
let main_window = initscr () in
1224
883
let small_window = newwin 10 5 20 10 in
1225
884
mvwaddstr main_window 10 2 "Hello";
1227
886
refresh();
1228
887
Unix.sleep 5;
1229
888
endwin()
1230
</PRE>To compile and link this program, run:
1231
<PRE CLASS="verbatim">
1232
ocamlc -custom -o test <span style="background-color:yellow; color:red">unix.cma</span> test.ml curses_stubs.o -cclib -lcurses
1233
</PRE>(On some machines, you may need to put <TT>-cclib -ltermcap</TT> or
1234
<TT>-cclib -lcurses -cclib -ltermcap</TT> instead of <TT>-cclib -lcurses</TT>.)<BR>
1235
<BR>
1236
1237
<H2 CLASS="section"><A NAME="htoc233">18.7</A> Advanced topic: callbacks from C to Caml</H2> <A NAME="s:callback"></A>
1238
1239
So far, we have described how to call C functions from Caml. In this
889
</PRE><P>To compile and link this program, run:
890
</P><PRE CLASS="verbatim"> ocamlc -custom -o test unix.cma test.ml curses_stubs.o -cclib -lcurses
891
</PRE><P>(On some machines, you may need to put <TT>-cclib -ltermcap</TT> or
892
<TT>-cclib -lcurses -cclib -ltermcap</TT> instead of <TT>-cclib -lcurses</TT>.)</P><H2 CLASS="section"><A NAME="htoc233">18.7</A>��Advanced topic: callbacks from C to Caml</H2><P> <A NAME="s:callback"></A>
893
</P><P>So far, we have described how to call C functions from Caml. In this
1240
894
section, we show how C functions can call Caml functions, either as
1241
895
callbacks (Caml calls C which calls Caml), or because the main program
1242
is written in C.<BR>
1243
<BR>
1244
1245
<H3 CLASS="subsection"><A NAME="htoc234">18.7.1</A> Applying Caml closures from C</H3> <A NAME="s:callbacks"></A>
1246
C functions can apply Caml functional values (closures) to Caml values.
896
is written in C.</P><H3 CLASS="subsection"><A NAME="htoc234">18.7.1</A>��Applying Caml closures from C</H3><P> <A NAME="s:callbacks"></A></P><P>C functions can apply Caml functional values (closures) to Caml values.
1247
897
The following functions are provided to perform the applications:
1248
<UL CLASS="itemize"><LI CLASS="li-itemize">
898
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
1249
899
<TT>caml_callback(</TT><I>f, a</I><TT>)</TT> applies the functional value <I>f</I> to
1250
the value <I>a</I> and return the value returned by <I>f</I>.
1251
<LI CLASS="li-itemize"><TT>caml_callback2(</TT><I>f, a, b</I><TT>)</TT> applies the functional value <I>f</I>
900
the value <I>a</I> and return the value returned by�<I>f</I>.
901
</LI><LI CLASS="li-itemize"><TT>caml_callback2(</TT><I>f, a, b</I><TT>)</TT> applies the functional value <I>f</I>
1252
902
(which is assumed to be a curried Caml function with two arguments) to
1253
903
<I>a</I> and <I>b</I>.
1254
<LI CLASS="li-itemize"><TT>caml_callback3(</TT><I>f, a, b, c</I><TT>)</TT> applies the functional value <I>f</I>
904
</LI><LI CLASS="li-itemize"><TT>caml_callback3(</TT><I>f, a, b, c</I><TT>)</TT> applies the functional value <I>f</I>
1255
905
(a curried Caml function with three arguments) to <I>a</I>, <I>b</I> and <I>c</I>.
1256
<LI CLASS="li-itemize"><TT>caml_callbackN(</TT><I>f, n, args</I><TT>)</TT> applies the functional value <I>f</I>
906
</LI><LI CLASS="li-itemize"><TT>caml_callbackN(</TT><I>f, n, args</I><TT>)</TT> applies the functional value <I>f</I>
1257
907
to the <I>n</I> arguments contained in the array of values <I>args</I>.
1258
</UL>
908
</LI></UL><P>
1259
909
If the function <I>f</I> does not return, but raises an exception that
1260
910
escapes the scope of the application, then this exception is
1261
911
propagated to the next enclosing Caml code, skipping over the C
1262
912
code. That is, if a Caml function <I>f</I> calls a C function <I>g</I> that
1263
913
calls back a Caml function <I>h</I> that raises a stray exception, then the
1264
914
execution of <I>g</I> is interrupted and the exception is propagated back
1265
into <I>f</I>.<BR>
1266
<BR>
1267
If the C code wishes to catch exceptions escaping the Caml function,
915
into <I>f</I>.</P><P>If the C code wishes to catch exceptions escaping the Caml function,
1268
916
it can use the functions <TT>caml_callback_exn</TT>, <TT>caml_callback2_exn</TT>,
1269
917
<TT>caml_callback3_exn</TT>, <TT>caml_callbackN_exn</TT>. These functions take the same
1270
918
arguments as their non-<TT>_exn</TT> counterparts, but catch escaping
1271
919
exceptions and return them to the C code. The return value <I>v</I> of the
1272
920
<TT>caml_callback*_exn</TT> functions must be tested with the macro
1273
<TT>Is_exception_result(</TT><I>v</I><TT>)</TT>. If the macro returns “false”, no
921
<TT>Is_exception_result(</TT><I>v</I><TT>)</TT>. If the macro returns “false”, no
1274
922
exception occured, and <I>v</I> is the value returned by the Caml
1275
function. If <TT>Is_exception_result(</TT><I>v</I><TT>)</TT> returns “true”,
923
function. If <TT>Is_exception_result(</TT><I>v</I><TT>)</TT> returns “true”,
1276
924
an exception escaped, and its value (the exception descriptor) can be
1277
recovered using <TT>Extract_exception(</TT><I>v</I><TT>)</TT>.<BR>
1278
<BR>
1279
1280
<H3 CLASS="subsection"><A NAME="htoc235">18.7.2</A> Registering Caml closures for use in C functions</H3>
1281
The main difficulty with the <TT>callback</TT> functions described above is
925
recovered using <TT>Extract_exception(</TT><I>v</I><TT>)</TT>.</P><H3 CLASS="subsection"><A NAME="htoc235">18.7.2</A>��Registering Caml closures for use in C functions</H3><P>The main difficulty with the <TT>callback</TT> functions described above is
1282
926
obtaining a closure to the Caml function to be called. For this
1283
927
purpose, Objective Caml provides a simple registration mechanism, by
1284
928
which Caml code can register Caml functions under some global name,
1285
929
and then C code can retrieve the corresponding closure by this global
1286
name.<BR>
1287
<BR>
1288
On the Caml side, registration is performed by evaluating
930
name.</P><P>On the Caml side, registration is performed by evaluating
1289
931
<TT>Callback.register</TT> <I>n v</I>. Here, <I>n</I> is the global name
1290
932
(an arbitrary string) and <I>v</I> the Caml value. For instance:
1291
<PRE CLASS="verbatim">
1292
let f x = print_string "f is applied to "; print_int n; print_newline()
933
</P><PRE CLASS="verbatim"> let f x = print_string "f is applied to "; print_int n; print_newline()
1293
934
let _ = Callback.register "test function" f
1294
</PRE>
1295
On the C side, a pointer to the value registered under name <I>n</I> is
935
</PRE><P>On the C side, a pointer to the value registered under name <I>n</I> is
1296
936
obtained by calling <TT>caml_named_value(</TT><I>n</I><TT>)</TT>. The returned
1297
937
pointer must then be dereferenced to recover the actual Caml value.
1298
938
If no value is registered under the name <I>n</I>, the null pointer is
1299
939
returned. For example, here is a C wrapper that calls the Caml function <TT>f</TT>
1300
940
above:
1301
<PRE CLASS="verbatim">
1302
void call_caml_f(int arg)
941
</P><PRE CLASS="verbatim"> void call_caml_f(int arg)
1303
942
{
1304
943
caml_callback(*caml_named_value("test function"), Val_int(arg));
1305
944
}
1306
</PRE>
1307
The pointer returned by <TT>caml_named_value</TT> is constant and can safely
945
</PRE><P>The pointer returned by <TT>caml_named_value</TT> is constant and can safely
1308
946
be cached in a C variable to avoid repeated name lookups. On the other
1309
947
hand, the value pointed to can change during garbage collection and
1310
948
must always be recomputed at the point of use. Here is a more
1311
949
efficient variant of <TT>call_caml_f</TT> above that calls <TT>caml_named_value</TT>
1312
950
only once:
1313
<PRE CLASS="verbatim">
1314
void call_caml_f(int arg)
951
</P><PRE CLASS="verbatim"> void call_caml_f(int arg)
1315
952
{
1316
953
static value * closure_f = NULL;
1317
954
if (closure_f == NULL) {
1320
957
}
1321
958
caml_callback(*closure_f, Val_int(arg));
1322
959
}
1323
</PRE>
1324
1325
<H3 CLASS="subsection"><A NAME="htoc236">18.7.3</A> Registering Caml exceptions for use in C functions</H3> <A NAME="s:register-exn"></A>
1326
The registration mechanism described above can also be used to
960
</PRE><H3 CLASS="subsection"><A NAME="htoc236">18.7.3</A>��Registering Caml exceptions for use in C functions</H3><P> <A NAME="s:register-exn"></A></P><P>The registration mechanism described above can also be used to
1327
961
communicate exception identifiers from Caml to C. The Caml code
1328
962
registers the exception by evaluating
1329
963
<TT>Callback.register_exception</TT> <I>n exn</I>, where <I>n</I> is an
1330
964
arbitrary name and <I>exn</I> is an exception value of the
1331
965
exception to register. For example:
1332
<PRE CLASS="verbatim">
1333
exception Error of string
966
</P><PRE CLASS="verbatim"> exception Error of string
1334
967
let _ = Callback.register_exception "test exception" (Error "any string")
1335
</PRE>The C code can then recover the exception identifier using
968
</PRE><P>The C code can then recover the exception identifier using
1336
969
<TT>caml_named_value</TT> and pass it as first argument to the functions
1337
970
<TT>raise_constant</TT>, <TT>raise_with_arg</TT>, and <TT>raise_with_string</TT> (described
1338
in section <A HREF="#s:c-exceptions">18.4.5</A>) to actually raise the exception. For
971
in section�<A HREF="#s:c-exceptions">18.4.5</A>) to actually raise the exception. For
1339
972
example, here is a C function that raises the <TT>Error</TT> exception with
1340
973
the given argument:
1341
<PRE CLASS="verbatim">
1342
void raise_error(char * msg)
974
</P><PRE CLASS="verbatim"> void raise_error(char * msg)
1343
975
{
1344
976
caml_raise_with_string(*caml_named_value("test exception"), msg);
1345
977
}
1346
</PRE>
1347
1348
<H3 CLASS="subsection"><A NAME="htoc237">18.7.4</A> Main program in C</H3> <A NAME="s:main-c"></A>
1349
In normal operation, a mixed Caml/C program starts by executing the
978
</PRE><H3 CLASS="subsection"><A NAME="htoc237">18.7.4</A>��Main program in C</H3><P> <A NAME="s:main-c"></A></P><P>In normal operation, a mixed Caml/C program starts by executing the
1350
979
Caml initialization code, which then may proceed to call C
1351
980
functions. We say that the main program is the Caml code. In some
1352
981
applications, it is desirable that the C code plays the role of the
1353
982
main program, calling Caml functions when needed. This can be achieved as
1354
983
follows:
1355
<UL CLASS="itemize"><LI CLASS="li-itemize">
984
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
1356
985
The C part of the program must provide a <TT>main</TT> function,
1357
986
which will override the default <TT>main</TT> function provided by the Caml
1358
987
runtime system. Execution will start in the user-defined <TT>main</TT> function
1359
just like for a regular C program.<BR>
1360
<BR>
1361
<LI CLASS="li-itemize">At some point, the C code must call <TT>caml_main(argv)</TT> to
988
just like for a regular C program.</LI><LI CLASS="li-itemize">At some point, the C code must call <TT>caml_main(argv)</TT> to
1362
989
initialize the Caml code. The <TT>argv</TT> argument is a C array of strings
1363
990
(type <TT>char **</TT>), terminated with a <TT>NULL</TT> pointer,
1364
991
which represents the command-line arguments, as
1365
992
passed as second argument to <TT>main</TT>. The Caml array <TT>Sys.argv</TT> will
1366
993
be initialized from this parameter. For the bytecode compiler,
1367
994
<TT>argv[0]</TT> and <TT>argv[1]</TT> are also consulted to find the file containing
1368
the bytecode.<BR>
1369
<BR>
1370
<LI CLASS="li-itemize">The call to <TT>caml_main</TT> initializes the Caml runtime system,
995
the bytecode.</LI><LI CLASS="li-itemize">The call to <TT>caml_main</TT> initializes the Caml runtime system,
1371
996
loads the bytecode (in the case of the bytecode compiler), and
1372
997
executes the initialization code of the Caml program. Typically, this
1373
998
initialization code registers callback functions using <TT>Callback.register</TT>.
1374
999
Once the Caml initialization code is complete, control returns to the
1375
C code that called <TT>caml_main</TT>.<BR>
1376
<BR>
1377
<LI CLASS="li-itemize">The C code can then invoke Caml functions using the callback
1378
mechanism (see section <A HREF="#s:callbacks">18.7.1</A>).
1379
</UL>
1380
1381
<H3 CLASS="subsection"><A NAME="htoc238">18.7.5</A> Embedding the Caml code in the C code</H3> <A NAME="s:embedded-code"></A>
1382
The bytecode compiler in custom runtime mode (<TT>ocamlc -custom</TT>)
1000
C code that called <TT>caml_main</TT>.</LI><LI CLASS="li-itemize">The C code can then invoke Caml functions using the callback
1001
mechanism (see section�<A HREF="#s:callbacks">18.7.1</A>).
1002
</LI></UL><H3 CLASS="subsection"><A NAME="htoc238">18.7.5</A>��Embedding the Caml code in the C code</H3><P> <A NAME="s:embedded-code"></A></P><P>The bytecode compiler in custom runtime mode (<TT>ocamlc -custom</TT>)
1383
1003
normally appends the bytecode to the executable file containing the
1384
1004
custom runtime. This has two consequences. First, the final linking
1385
1005
step must be performed by <TT>ocamlc</TT>. Second, the Caml runtime library
1386
1006
must be able to find the name of the executable file from the
1387
1007
command-line arguments. When using <TT>caml_main(argv)</TT> as in
1388
section <A HREF="#s:main-c">18.7.4</A>, this means that <TT>argv[0]</TT> or <TT>argv[1]</TT> must
1389
contain the executable file name.<BR>
1390
<BR>
1391
An alternative is to embed the bytecode in the C code. The
1008
section�<A HREF="#s:main-c">18.7.4</A>, this means that <TT>argv[0]</TT> or <TT>argv[1]</TT> must
1009
contain the executable file name.</P><P>An alternative is to embed the bytecode in the C code. The
1392
1010
<TT>-output-obj</TT> option to <TT>ocamlc</TT> is provided for this purpose.
1393
1011
It causes the <TT>ocamlc</TT> compiler to output a C object file (<TT>.o</TT> file)
1394
1012
containing the bytecode for the Caml part of the program, as well as a
1395
1013
<TT>caml_startup</TT> function. The C object file produced by <TT>ocamlc -output-obj</TT> can then be linked with C code using the standard C
1396
compiler, or stored in a C library.<BR>
1397
<BR>
1398
The <TT>caml_startup</TT> function must be called from the main C program in
1014
compiler, or stored in a C library.</P><P>The <TT>caml_startup</TT> function must be called from the main C program in
1399
1015
order to initialize the Caml runtime and execute the Caml
1400
1016
initialization code. Just like <TT>caml_main</TT>, it takes one <TT>argv</TT>
1401
1017
parameter containing the command-line parameters. Unlike <TT>caml_main</TT>,
1402
1018
this <TT>argv</TT> parameter is used only to initialize <TT>Sys.argv</TT>, but not
1403
for finding the name of the executable file.<BR>
1404
<BR>
1405
The native-code compiler <TT>ocamlopt</TT> also supports the <TT>-output-obj</TT>
1019
for finding the name of the executable file.</P><P>The native-code compiler <TT>ocamlopt</TT> also supports the <TT>-output-obj</TT>
1406
1020
option, causing it to output a C object file containing the native
1407
1021
code for all Caml modules on the command-line, as well as the Caml
1408
1022
startup code. Initialization is performed by calling <TT>caml_startup</TT> as
1409
in the case of the bytecode compiler.<BR>
1410
<BR>
1411
For the final linking phase, in addition to the object file produced
1023
in the case of the bytecode compiler.</P><P>For the final linking phase, in addition to the object file produced
1412
1024
by <TT>-output-obj</TT>, you will have to provide the Objective Caml runtime
1413
1025
library (<TT>libcamlrun.a</TT> for bytecode, <TT>libasmrun.a</TT> for native-code),
1414
1026
as well as all C libraries that are required by the Caml libraries
1415
1027
used. For instance, assume the Caml part of your program uses the
1416
1028
Unix library. With <TT>ocamlc</TT>, you should do:
1417
<PRE>
1029
</P><PRE>
1418
1030
ocamlc -output-obj -o camlcode.o unix.cma <I>other</I> .cmo <I>and</I> .cma <I>files</I>
1419
1031
cc -o myprog <I>C objects and libraries</I> \
1420
1032
camlcode.o -L/usr/local/lib/ocaml -lunix -lcamlrun
1421
</PRE>
1033
</PRE><P>
1422
1034
With <TT>ocamlopt</TT>, you should do:
1423
<PRE>
1035
</P><PRE>
1424
1036
ocamlopt -output-obj -o camlcode.o unix.cmxa <I>other</I> .cmx <I>and</I> .cmxa <I>files</I>
1425
1037
cc -o myprog <I>C objects and libraries</I> \
1426
1038
camlcode.o -L/usr/local/lib/ocaml -lunix -lasmrun
1427
</PRE>
1428
1429
<H5 CLASS="paragraph">Warning:</H5> On some ports, special options are required on the final
1039
</PRE><H5 CLASS="paragraph">Warning:</H5><P> On some ports, special options are required on the final
1430
1040
linking phase that links together the object file produced by the
1431
1041
<TT>-output-obj</TT> option and the remainder of the program. Those options
1432
1042
are shown in the configuration file <TT>config/Makefile</TT> generated during
1434
1044
(for object files produced by <TT>ocamlc -output-obj</TT>) and
1435
1045
<TT>NATIVECCLINKOPTS</TT> (for object files produced by <TT>ocamlopt -output-obj</TT>). Currently, the only ports that require special
1436
1046
attention are:
1437
<UL CLASS="itemize"><LI CLASS="li-itemize">
1047
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
1438
1048
Alpha under Digital Unix / Tru64 Unix with <TT>gcc</TT>:
1439
1049
object files produced by <TT>ocamlc -output-obj</TT> must be linked with the
1440
1050
<TT>gcc</TT> options <TT>-Wl,-T,12000000 -Wl,-D,14000000</TT>.
1441
1051
This is not necessary for object files produced by <TT>ocamlopt -output-obj</TT>.
1442
<LI CLASS="li-itemize">Windows NT: the object file produced by Objective Caml have been
1052
</LI><LI CLASS="li-itemize">Windows NT: the object file produced by Objective Caml have been
1443
1053
compiled with the <TT>/MT</TT> flag, and therefore all other object files
1444
1054
linked with it should also be compiled with <TT>/MT</TT>.
1445
</UL>
1446
1447
<H2 CLASS="section"><A NAME="htoc239">18.8</A> Advanced example with callbacks</H2>
1448
1449
This section illustrates the callback facilities described in
1450
section <A HREF="#s:callback">18.7</A>. We are going to package some Caml functions
1055
</LI></UL><H2 CLASS="section"><A NAME="htoc239">18.8</A>��Advanced example with callbacks</H2><P>This section illustrates the callback facilities described in
1056
section�<A HREF="#s:callback">18.7</A>. We are going to package some Caml functions
1451
1057
in such a way that they can be linked with C code and called from C
1452
1058
just like any C functions. The Caml functions are defined in the
1453
following <TT>mod.ml</TT> Caml source:
1454
<PRE CLASS="verbatim">
1455
(* File mod.ml -- some ``useful'' Caml functions *)
1059
following <TT>mod.ml</TT> Caml source:</P><PRE CLASS="verbatim">(* File mod.ml -- some ``useful'' Caml functions *)
1456
1060
1457
1061
let rec fib n = if n < 2 then 1 else fib(n-1) + fib(n-2)
1458
1062
1462
1066
1463
1067
let _ = Callback.register "fib" fib
1464
1068
let _ = Callback.register "format_result" format_result
1465
</PRE>
1466
Here is the C stub code for calling these functions from C:
1467
<PRE CLASS="verbatim">
1468
/* File modwrap.c -- wrappers around the Caml functions */
1069
</PRE><P>Here is the C stub code for calling these functions from C:</P><PRE CLASS="verbatim">/* File modwrap.c -- wrappers around the Caml functions */
1469
1070
1470
1071
#include <stdio.h>
1471
1072
#include <string.h>
1488
1089
/* We copy the C string returned by String_val to the C heap
1489
1090
so that it remains valid after garbage collection. */
1490
1091
}
1491
</PRE>
1492
We now compile the Caml code to a C object file and put it in a C
1092
</PRE><P>We now compile the Caml code to a C object file and put it in a C
1493
1093
library along with the stub code in <TT>modwrap.c</TT> and the Caml runtime system:
1494
<PRE CLASS="verbatim">
1495
ocamlc -custom -output-obj -o modcaml.o mod.ml
1094
</P><PRE CLASS="verbatim"> ocamlc -custom -output-obj -o modcaml.o mod.ml
1496
1095
ocamlc -c modwrap.c
1497
1096
cp /usr/local/lib/ocaml/libcamlrun.a mod.a
1498
1097
ar r mod.a modcaml.o modwrap.o
1499
</PRE>(One can also use <TT>ocamlopt -output-obj</TT> instead of <TT>ocamlc -custom -output-obj</TT>. In this case, replace <TT>libcamlrun.a</TT> (the bytecode
1500
runtime library) by <TT>libasmrun.a</TT> (the native-code runtime library).)<BR>
1501
<BR>
1502
Now, we can use the two functions <TT>fib</TT> and <TT>format_result</TT> in any C
1098
</PRE><P>(One can also use <TT>ocamlopt -output-obj</TT> instead of <TT>ocamlc -custom -output-obj</TT>. In this case, replace <TT>libcamlrun.a</TT> (the bytecode
1099
runtime library) by <TT>libasmrun.a</TT> (the native-code runtime library).)</P><P>Now, we can use the two functions <TT>fib</TT> and <TT>format_result</TT> in any C
1503
1100
program, just like regular C functions. Just remember to call
1504
<TT>caml_startup</TT> once before.
1505
<PRE CLASS="verbatim">
1506
/* File main.c -- a sample client for the Caml functions */
1101
<TT>caml_startup</TT> once before.</P><PRE CLASS="verbatim">/* File main.c -- a sample client for the Caml functions */
1507
1102
1508
1103
#include <stdio.h>
1509
1104
1518
1113
printf("fib(10) = %s\n", format_result(result));
1519
1114
return 0;
1520
1115
}
1521
</PRE>
1522
To build the whole program, just invoke the C compiler as follows:
1523
<PRE CLASS="verbatim">
1524
cc -o prog main.c mod.a -lcurses
1525
</PRE>(On some machines, you may need to put <TT>-ltermcap</TT> or
1526
<TT>-lcurses -ltermcap</TT> instead of <TT>-lcurses</TT>.)<BR>
1527
<BR>
1528
1529
<H2 CLASS="section"><A NAME="htoc240">18.9</A> Advanced topic: custom blocks</H2> <A NAME="s:custom"></A>
1530
1531
Blocks with tag <TT>Custom_tag</TT> contain both arbitrary user data and a
1116
</PRE><P>To build the whole program, just invoke the C compiler as follows:
1117
</P><PRE CLASS="verbatim"> cc -o prog main.c mod.a -lcurses
1118
</PRE><P>(On some machines, you may need to put <TT>-ltermcap</TT> or
1119
<TT>-lcurses -ltermcap</TT> instead of <TT>-lcurses</TT>.)</P><H2 CLASS="section"><A NAME="htoc240">18.9</A>��Advanced topic: custom blocks</H2><P> <A NAME="s:custom"></A>
1120
</P><P>Blocks with tag <TT>Custom_tag</TT> contain both arbitrary user data and a
1532
1121
pointer to a C struct, with type <TT>struct custom_operations</TT>, that
1533
1122
associates user-provided finalization, comparison, hashing,
1534
serialization and deserialization functions to this block.<BR>
1535
<BR>
1536
1537
<H3 CLASS="subsection"><A NAME="htoc241">18.9.1</A> The <TT>struct custom_operations</TT></H3>
1538
The <TT>struct custom_operations</TT> is defined in <TT><caml/custom.h></TT> and
1123
serialization and deserialization functions to this block.</P><H3 CLASS="subsection"><A NAME="htoc241">18.9.1</A>��The <TT>struct custom_operations</TT></H3><P>The <TT>struct custom_operations</TT> is defined in <TT><caml/custom.h></TT> and
1539
1124
contains the following fields:
1540
<UL CLASS="itemize"><LI CLASS="li-itemize">
1125
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
1541
1126
<TT>char *identifier</TT><BR>
1542
1127
A zero-terminated character string serving as an identifier for
1543
serialization and deserialization operations.<BR>
1544
<BR>
1545
<LI CLASS="li-itemize"><TT>void (*finalize)(value v)</TT><BR>
1128
serialization and deserialization operations.</LI><LI CLASS="li-itemize"><TT>void (*finalize)(value v)</TT><BR>
1546
1129
The <TT>finalize</TT> field contains a pointer to a C function that is called
1547
1130
when the block becomes unreachable and is about to be reclaimed.
1548
1131
The block is passed as first argument to the function.
1549
The <TT>finalize</TT> field can also be
1550
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
1551
<STRIKE>NULL</STRIKE>
1552
<TT>custom_finalize_default</TT>
1553
</div>
1554
to indicate that no
1555
finalization function is associated with the block.
1556
Important note: the <TT>v</TT> parameter of this function is of type <TT>value</TT>, but
1557
it must not be declared using the <TT>CAMLparam</TT> macros.<BR>
1558
<BR>
1559
<LI CLASS="li-itemize"><TT>int (*compare)(value v1, value v2)</TT><BR>
1132
The <TT>finalize</TT> field can also be <TT>custom_finalize_default</TT> to indicate that no
1133
finalization function is associated with the block.</LI><LI CLASS="li-itemize"><TT>int (*compare)(value v1, value v2)</TT><BR>
1560
1134
The <TT>compare</TT> field contains a pointer to a C function that is
1561
1135
called whenever two custom blocks are compared using Caml's generic
1562
1136
comparison operators (<TT>=</TT>, <TT><></TT>, <TT><=</TT>, <TT>>=</TT>, <TT><</TT>, <TT>></TT> and
1564
1138
the two blocks are structurally equal, a negative integer if the data
1565
1139
from the first block is less than the data from the second block, and
1566
1140
a positive integer if the data from the first block is greater than
1567
the data from the second block.
1568
Note: You must use <TT>CAMLparam</TT> to declare <TT>v1</TT> and <TT>v2</TT> and <TT>CAMLreturn</TT>
1569
to return the result.<BR>
1570
<BR>
1571
The <TT>compare</TT> field can be set to <TT>custom_compare_default</TT>; this
1572
default comparison function simply raises <TT>Failure</TT>.<BR>
1573
<BR>
1574
<LI CLASS="li-itemize"><TT>long (*hash)(value v)</TT><BR>
1141
the data from the second block.<P>The <TT>compare</TT> field can be set to <TT>custom_compare_default</TT>; this
1142
default comparison function simply raises <TT>Failure</TT>.</P></LI><LI CLASS="li-itemize"><TT>long (*hash)(value v)</TT><BR>
1575
1143
The <TT>hash</TT> field contains a pointer to a C function that is called
1576
1144
whenever Caml's generic hash operator (see module <TT>Hashtbl</TT>) is
1577
1145
applied to a custom block. The C function can return an arbitrary
1579
1147
given custom block. The hash value must be compatible with the
1580
1148
<TT>compare</TT> function, in the sense that two structurally equal data
1581
1149
(that is, two custom blocks for which <TT>compare</TT> returns 0) must have
1582
the same hash value.
1583
Note: You must use <TT>CAMLparam</TT> to declare <TT>v</TT> and <TT>CAMLreturn</TT>
1584
to return the result.<BR>
1585
<BR>
1586
The <TT>hash</TT> field can be set to <TT>custom_hash_default</TT>, in which case
1587
the custom block is ignored during hash computation.<BR>
1588
<BR>
1589
<LI CLASS="li-itemize"><TT>void (*serialize)(value v, unsigned long * wsize_32, unsigned long * wsize_64)</TT><BR>
1150
the same hash value.<P>The <TT>hash</TT> field can be set to <TT>custom_hash_default</TT>, in which case
1151
the custom block is ignored during hash computation.</P></LI><LI CLASS="li-itemize"><TT>void (*serialize)(value v, unsigned long * wsize_32, unsigned long * wsize_64)</TT><BR>
1590
1152
The <TT>serialize</TT> field contains a pointer to a C function that is
1591
1153
called whenever the custom block needs to be serialized (marshaled)
1592
1154
using the Caml functions <TT>output_value</TT> or <TT>Marshal.to_...</TT>.
1598
1160
below. The user-provided <TT>serialize</TT> function must then store in its
1599
1161
<TT>wsize_32</TT> and <TT>wsize_64</TT> parameters the sizes in bytes of the data
1600
1162
part of the custom block on a 32-bit architecture and on a 64-bit
1601
architecture, respectively.
1602
Note: You must use <TT>CAMLparam</TT> to declare <TT>v</TT> and <TT>CAMLreturn</TT>
1603
to return the result.<BR>
1604
<BR>
1605
The <TT>serialize</TT> field can be set to <TT>custom_serialize_default</TT>,
1163
architecture, respectively.<P>The <TT>serialize</TT> field can be set to <TT>custom_serialize_default</TT>,
1606
1164
in which case the <TT>Failure</TT> exception is raised when attempting to
1607
serialize the custom block.<BR>
1608
<BR>
1609
<LI CLASS="li-itemize"><TT>unsigned long (*deserialize)(void * dst)</TT><BR>
1165
serialize the custom block.</P></LI><LI CLASS="li-itemize"><TT>unsigned long (*deserialize)(void * dst)</TT><BR>
1610
1166
The <TT>deserialize</TT> field contains a pointer to a C function that is
1611
1167
called whenever a custom block with identifier <TT>identifier</TT> needs to
1612
1168
be deserialized (un-marshaled) using the Caml functions <TT>input_value</TT>
1618
1174
returns the size in bytes of the data part of the custom block.
1619
1175
This size must be identical to the <TT>wsize_32</TT> result of
1620
1176
the <TT>serialize</TT> operation if the architecture is 32 bits, or
1621
<TT>wsize_64</TT> if the architecture is 64 bits.<BR>
1622
<BR>
1623
The <TT>deserialize</TT> field can be set to <TT>custom_deserialize_default</TT>
1177
<TT>wsize_64</TT> if the architecture is 64 bits.<P>The <TT>deserialize</TT> field can be set to <TT>custom_deserialize_default</TT>
1624
1178
to indicate that deserialization is not supported. In this case,
1625
1179
do not register the <TT>struct custom_operations</TT> with the deserializer
1626
1180
using <TT>register_custom_operations</TT> (see below).
1627
</UL>
1628
1629
<H3 CLASS="subsection"><A NAME="htoc242">18.9.2</A> Allocating custom blocks</H3>
1630
Custom blocks must be allocated via the <TT>caml_alloc_custom</TT> function.
1181
</P></LI></UL><P>Note: the <TT>finalize</TT>, <TT>compare</TT>, <TT>hash</TT>, <TT>serialize</TT> and <TT>deserialize</TT>
1182
functions attached to custom block descriptors must never trigger a
1183
garbage collection. Within these functions, do not call any of the
1184
Caml allocation functions, and do not perform a callback into Caml
1185
code. Do not use <TT>CAMLparam</TT> to register the parameters to these
1186
functions, and do not use <TT>CAMLreturn</TT> to return the result.</P><H3 CLASS="subsection"><A NAME="htoc242">18.9.2</A>��Allocating custom blocks</H3><P>Custom blocks must be allocated via the <TT>caml_alloc_custom</TT> function.
1631
1187
<TT>caml_alloc_custom(</TT><I>ops</I><TT>, </TT><I>size</I><TT>, </TT><I>used</I><TT>, </TT><I>max</I><TT>)</TT>
1632
1188
returns a fresh custom block, with room for <I>size</I> bytes of user
1633
1189
data, and whose associated operations are given by <I>ops</I> (a
1634
1190
pointer to a <TT>struct custom_operations</TT>, usually statically allocated
1635
as a C global variable). <BR>
1636
<BR>
1637
The two parameters <I>used</I> and <I>max</I> are used to control the
1191
as a C global variable). </P><P>The two parameters <I>used</I> and <I>max</I> are used to control the
1638
1192
speed of garbage collection when the finalized object contains
1639
1193
pointers to out-of-heap resources. Generally speaking, the
1640
1194
Caml incremental major collector adjusts its speed relative to the
1641
1195
allocation rate of the program. The faster the program allocates, the
1642
1196
harder the GC works in order to reclaim quickly unreachable blocks
1643
and avoid having large amount of “floating garbage” (unreferenced
1644
objects that the GC has not yet collected).<BR>
1645
<BR>
1646
Normally, the allocation rate is measured by counting the in-heap size
1197
and avoid having large amount of “floating garbage” (unreferenced
1198
objects that the GC has not yet collected).</P><P>Normally, the allocation rate is measured by counting the in-heap size
1647
1199
of allocated blocks. However, it often happens that finalized
1648
1200
objects contain pointers to out-of-heap memory blocks and other resources
1649
1201
(such as file descriptors, X Windows bitmaps, etc.). For those
1650
1202
blocks, the in-heap size of blocks is not a good measure of the
1651
quantity of resources allocated by the program.<BR>
1652
<BR>
1653
The two arguments <I>used</I> and <I>max</I> give the GC an idea of how
1203
quantity of resources allocated by the program.</P><P>The two arguments <I>used</I> and <I>max</I> give the GC an idea of how
1654
1204
much out-of-heap resources are consumed by the finalized block
1655
1205
being allocated: you give the amount of resources allocated to this
1656
1206
object as parameter <I>used</I>, and the maximum amount that you want
1657
1207
to see in floating garbage as parameter <I>max</I>. The units are
1658
arbitrary: the GC cares only about the ratio <I>used</I> / <I>max</I>.<BR>
1659
<BR>
1660
For instance, if you are allocating a finalized block holding an X
1208
arbitrary: the GC cares only about the ratio <I>used</I> / <I>max</I>.</P><P>For instance, if you are allocating a finalized block holding an X
1661
1209
Windows bitmap of <I>w</I> by <I>h</I> pixels, and you'd rather not
1662
1210
have more than 1 mega-pixels of unreclaimed bitmaps, specify
1663
<I>used</I> = <I>w</I> * <I>h</I> and <I>max</I> = 1000000.<BR>
1664
<BR>
1665
Another way to describe the effect of the <I>used</I> and <I>max</I>
1211
<I>used</I> = <I>w</I> * <I>h</I> and <I>max</I> = 1000000.</P><P>Another way to describe the effect of the <I>used</I> and <I>max</I>
1666
1212
parameters is in terms of full GC cycles. If you allocate many custom
1667
1213
blocks with <I>used</I> / <I>max</I> = 1 / <I>N</I>, the GC will then do one
1668
1214
full cycle (examining every object in the heap and calling
1669
1215
finalization functions on those that are unreachable) every <I>N</I>
1670
1216
allocations. For instance, if <I>used</I> = 1 and <I>max</I> = 1000,
1671
1217
the GC will do one full cycle at least every 1000 allocations of
1672
custom blocks.<BR>
1673
<BR>
1674
If your finalized blocks contain no pointers to out-of-heap resources,
1218
custom blocks.</P><P>If your finalized blocks contain no pointers to out-of-heap resources,
1675
1219
or if the previous discussion made little sense to you, just take
1676
1220
<I>used</I> = 0 and <I>max</I> = 1. But if you later find that the
1677
finalization functions are not called “often enough”, consider
1678
increasing the <I>used</I> / <I>max</I> ratio.<BR>
1679
<BR>
1680
1681
<H3 CLASS="subsection"><A NAME="htoc243">18.9.3</A> Accessing custom blocks</H3>
1682
The data part of a custom block <I>v</I> can be
1221
finalization functions are not called “often enough”, consider
1222
increasing the <I>used</I> / <I>max</I> ratio.</P><H3 CLASS="subsection"><A NAME="htoc243">18.9.3</A>��Accessing custom blocks</H3><P>The data part of a custom block <I>v</I> can be
1683
1223
accessed via the pointer <TT>Data_custom_val(</TT><I>v</I><TT>)</TT>. This pointer
1684
1224
has type <TT>void *</TT> and should be cast to the actual type of the data
1685
stored in the custom block.<BR>
1686
<BR>
1687
The contents of custom blocks are not scanned by the garbage
1225
stored in the custom block.</P><P>The contents of custom blocks are not scanned by the garbage
1688
1226
collector, and must therefore not contain any pointer inside the Caml
1689
1227
heap. In other terms, never store a Caml <TT>value</TT> in a custom block,
1690
1228
and do not use <TT>Field</TT>, <TT>Store_field</TT> nor <TT>modify</TT> to access the data
1691
1229
part of a custom block. Conversely, any C data structure (not
1692
containing heap pointers) can be stored in a custom block.<BR>
1693
<BR>
1694
1695
<H3 CLASS="subsection"><A NAME="htoc244">18.9.4</A> Writing custom serialization and deserialization functions</H3>
1696
The following functions, defined in <TT><caml/intext.h></TT>, are provided to
1230
containing heap pointers) can be stored in a custom block.</P><H3 CLASS="subsection"><A NAME="htoc244">18.9.4</A>��Writing custom serialization and deserialization functions</H3><P>The following functions, defined in <TT><caml/intext.h></TT>, are provided to
1697
1231
write and read back the contents of custom blocks in a portable way.
1698
1232
Those functions handle endianness conversions when e.g. data is
1699
written on a little-endian machine and read back on a big-endian machine.<BR>
1700
<BR>
1701
<DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
1702
<TR><TD ALIGN=center NOWRAP><B>Function</B></TD>
1703
<TD ALIGN=center NOWRAP><B>Action</B></TD>
1704
</TR>
1233
written on a little-endian machine and read back on a big-endian machine.</P><DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%"><TR><TD ALIGN=center NOWRAP><B>Function</B></TD><TD ALIGN=center NOWRAP><B>Action</B></TD></TR>
1705
1234
<TR><TD VALIGN=top ALIGN=left NOWRAP>
1706
<TT>caml_serialize_int_1</TT></TD>
1707
<TD VALIGN=top ALIGN=left>Write a 1-byte integer</TD>
1708
</TR>
1709
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_int_2</TT></TD>
1710
<TD VALIGN=top ALIGN=left>Write a 2-byte integer</TD>
1711
</TR>
1712
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_int_4</TT></TD>
1713
<TD VALIGN=top ALIGN=left>Write a 4-byte integer</TD>
1714
</TR>
1715
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_int_8</TT></TD>
1716
<TD VALIGN=top ALIGN=left>Write a 8-byte integer</TD>
1717
</TR>
1718
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_float_4</TT></TD>
1719
<TD VALIGN=top ALIGN=left>Write a 4-byte float</TD>
1720
</TR>
1721
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_float_8</TT></TD>
1722
<TD VALIGN=top ALIGN=left>Write a 8-byte float</TD>
1723
</TR>
1724
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_1</TT></TD>
1725
<TD VALIGN=top ALIGN=left>Write an array of 1-byte quantities</TD>
1726
</TR>
1727
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_2</TT></TD>
1728
<TD VALIGN=top ALIGN=left>Write an array of 2-byte quantities</TD>
1729
</TR>
1730
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_4</TT></TD>
1731
<TD VALIGN=top ALIGN=left>Write an array of 4-byte quantities</TD>
1732
</TR>
1733
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_8</TT></TD>
1734
<TD VALIGN=top ALIGN=left>Write an array of 8-byte quantities</TD>
1735
</TR>
1736
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_1</TT></TD>
1737
<TD VALIGN=top ALIGN=left>Read an unsigned 1-byte integer</TD>
1738
</TR>
1739
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_1</TT></TD>
1740
<TD VALIGN=top ALIGN=left>Read a signed 1-byte integer</TD>
1741
</TR>
1742
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_2</TT></TD>
1743
<TD VALIGN=top ALIGN=left>Read an unsigned 2-byte integer</TD>
1744
</TR>
1745
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_2</TT></TD>
1746
<TD VALIGN=top ALIGN=left>Read a signed 2-byte integer</TD>
1747
</TR>
1748
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_4</TT></TD>
1749
<TD VALIGN=top ALIGN=left>Read an unsigned 4-byte integer</TD>
1750
</TR>
1751
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_4</TT></TD>
1752
<TD VALIGN=top ALIGN=left>Read a signed 4-byte integer</TD>
1753
</TR>
1754
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_8</TT></TD>
1755
<TD VALIGN=top ALIGN=left>Read an unsigned 8-byte integer</TD>
1756
</TR>
1757
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_8</TT></TD>
1758
<TD VALIGN=top ALIGN=left>Read a signed 8-byte integer</TD>
1759
</TR>
1760
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_float_4</TT></TD>
1761
<TD VALIGN=top ALIGN=left>Read a 4-byte float</TD>
1762
</TR>
1763
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_float_8</TT></TD>
1764
<TD VALIGN=top ALIGN=left>Read an 8-byte float</TD>
1765
</TR>
1766
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_1</TT></TD>
1767
<TD VALIGN=top ALIGN=left>Read an array of 1-byte quantities</TD>
1768
</TR>
1769
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_2</TT></TD>
1770
<TD VALIGN=top ALIGN=left>Read an array of 2-byte quantities</TD>
1771
</TR>
1772
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_4</TT></TD>
1773
<TD VALIGN=top ALIGN=left>Read an array of 4-byte quantities</TD>
1774
</TR>
1775
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_8</TT></TD>
1776
<TD VALIGN=top ALIGN=left>Read an array of 8-byte quantities</TD>
1777
</TR>
1778
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_error</TT></TD>
1779
<TD VALIGN=top ALIGN=left>Signal an error during deserialization;
1235
<TT>caml_serialize_int_1</TT></TD><TD VALIGN=top ALIGN=left>Write a 1-byte integer</TD></TR>
1236
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_int_2</TT></TD><TD VALIGN=top ALIGN=left>Write a 2-byte integer</TD></TR>
1237
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_int_4</TT></TD><TD VALIGN=top ALIGN=left>Write a 4-byte integer</TD></TR>
1238
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_int_8</TT></TD><TD VALIGN=top ALIGN=left>Write a 8-byte integer</TD></TR>
1239
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_float_4</TT></TD><TD VALIGN=top ALIGN=left>Write a 4-byte float</TD></TR>
1240
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_float_8</TT></TD><TD VALIGN=top ALIGN=left>Write a 8-byte float</TD></TR>
1241
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_1</TT></TD><TD VALIGN=top ALIGN=left>Write an array of 1-byte quantities</TD></TR>
1242
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_2</TT></TD><TD VALIGN=top ALIGN=left>Write an array of 2-byte quantities</TD></TR>
1243
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_4</TT></TD><TD VALIGN=top ALIGN=left>Write an array of 4-byte quantities</TD></TR>
1244
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_serialize_block_8</TT></TD><TD VALIGN=top ALIGN=left>Write an array of 8-byte quantities</TD></TR>
1245
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_1</TT></TD><TD VALIGN=top ALIGN=left>Read an unsigned 1-byte integer</TD></TR>
1246
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_1</TT></TD><TD VALIGN=top ALIGN=left>Read a signed 1-byte integer</TD></TR>
1247
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_2</TT></TD><TD VALIGN=top ALIGN=left>Read an unsigned 2-byte integer</TD></TR>
1248
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_2</TT></TD><TD VALIGN=top ALIGN=left>Read a signed 2-byte integer</TD></TR>
1249
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_4</TT></TD><TD VALIGN=top ALIGN=left>Read an unsigned 4-byte integer</TD></TR>
1250
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_4</TT></TD><TD VALIGN=top ALIGN=left>Read a signed 4-byte integer</TD></TR>
1251
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_uint_8</TT></TD><TD VALIGN=top ALIGN=left>Read an unsigned 8-byte integer</TD></TR>
1252
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_sint_8</TT></TD><TD VALIGN=top ALIGN=left>Read a signed 8-byte integer</TD></TR>
1253
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_float_4</TT></TD><TD VALIGN=top ALIGN=left>Read a 4-byte float</TD></TR>
1254
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_float_8</TT></TD><TD VALIGN=top ALIGN=left>Read an 8-byte float</TD></TR>
1255
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_1</TT></TD><TD VALIGN=top ALIGN=left>Read an array of 1-byte quantities</TD></TR>
1256
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_2</TT></TD><TD VALIGN=top ALIGN=left>Read an array of 2-byte quantities</TD></TR>
1257
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_4</TT></TD><TD VALIGN=top ALIGN=left>Read an array of 4-byte quantities</TD></TR>
1258
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_block_8</TT></TD><TD VALIGN=top ALIGN=left>Read an array of 8-byte quantities</TD></TR>
1259
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>caml_deserialize_error</TT></TD><TD VALIGN=top ALIGN=left>Signal an error during deserialization;
1780
1260
<TT>input_value</TT> or <TT>Marshal.from_...</TT> raise a <TT>Failure</TT> exception after
1781
cleaning up their internal data structures</TD>
1782
</TR></TABLE></DIV><BR>
1783
<BR>
1784
Serialization functions are attached to the custom blocks to which
1261
cleaning up their internal data structures</TD></TR>
1262
</TABLE></DIV><P>Serialization functions are attached to the custom blocks to which
1785
1263
they apply. Obviously, deserialization functions cannot be attached
1786
1264
this way, since the custom block does not exist yet when
1787
1265
deserialization begins! Thus, the <TT>struct custom_operations</TT> that
1791
1269
reading the identifier off the input stream, allocating a custom block
1792
1270
of the size specified in the input stream, searching the registered
1793
1271
<TT>struct custom_operation</TT> blocks for one with the same identifier, and
1794
calling its <TT>deserialize</TT> function to fill the data part of the custom block.<BR>
1795
<BR>
1796
1797
<H3 CLASS="subsection"><A NAME="htoc245">18.9.5</A> Choosing identifiers</H3>
1798
Identifiers in <TT>struct custom_operations</TT> must be chosen carefully,
1272
calling its <TT>deserialize</TT> function to fill the data part of the custom block.</P><H3 CLASS="subsection"><A NAME="htoc245">18.9.5</A>��Choosing identifiers</H3><P>Identifiers in <TT>struct custom_operations</TT> must be chosen carefully,
1799
1273
since they must identify uniquely the data structure for serialization
1800
1274
and deserialization operations. In particular, consider including a
1801
1275
version number in the identifier; this way, the format of the data can
1802
1276
be changed later, yet backward-compatible deserialisation functions
1803
can be provided.<BR>
1804
<BR>
1805
Identifiers starting with <TT>_</TT> (an underscore character) are reserved
1277
can be provided.</P><P>Identifiers starting with <TT>_</TT> (an underscore character) are reserved
1806
1278
for the Objective Caml runtime system; do not use them for your custom
1807
1279
data. We recommend to use a URL
1808
1280
(<TT>http://mymachine.mydomain.com/mylibrary/version-number</TT>)
1809
1281
or a Java-style package name
1810
1282
(<TT>com.mydomain.mymachine.mylibrary.version-number</TT>)
1811
as identifiers, to minimize the risk of identifier collision.<BR>
1812
<BR>
1813
1814
<H3 CLASS="subsection"><A NAME="htoc246">18.9.6</A> Finalized blocks</H3>
1815
Custom blocks generalize the finalized blocks that were present in
1283
as identifiers, to minimize the risk of identifier collision.</P><H3 CLASS="subsection"><A NAME="htoc246">18.9.6</A>��Finalized blocks</H3><P>Custom blocks generalize the finalized blocks that were present in
1816
1284
Objective Caml prior to version 3.00. For backward compatibility, the
1817
1285
format of custom blocks is compatible with that of finalized blocks,
1818
1286
and the <TT>alloc_final</TT> function is still available to allocate a custom
1822
1290
word is reserved for storing the custom operations; the other
1823
1291
<I>n</I>-1 words are available for your data. The two parameters
1824
1292
<I>used</I> and <I>max</I> are used to control the speed of garbage
1825
collection, as described for <TT>caml_alloc_custom</TT>.<BR>
1826
<BR>
1827
1828
<H2 CLASS="section"><A NAME="htoc247">18.10</A> Building mixed C/Caml libraries: <TT>ocamlmklib</TT></H2> <A NAME="s-ocamlmklib"></A>
1829
The <TT>ocamlmklib</TT> command facilitates the construction of libraries
1293
collection, as described for <TT>caml_alloc_custom</TT>.</P><H2 CLASS="section"><A NAME="htoc247">18.10</A>��Building mixed C/Caml libraries: <TT>ocamlmklib</TT></H2><P> <A NAME="s-ocamlmklib"></A></P><P>The <TT>ocamlmklib</TT> command facilitates the construction of libraries
1830
1294
containing both Caml code and C code, and usable both in static
1831
linking and dynamic linking modes.<BR>
1832
<BR>
1833
1834
<FONT COLOR=purple>Windows:</FONT>
1835
<BLOCKQUOTE CLASS="quote"> This command is available only under Cygwin, but not for the
1295
linking and dynamic linking modes.</P><BLOCKQUOTE CLASS="quote"><FONT COLOR=purple>Windows:</FONT>�� This command is available only under Cygwin, but not for the
1836
1296
native Win32 port.
1837
</BLOCKQUOTE>
1838
The <TT>ocamlmklib</TT> command takes three kinds of arguments:
1839
<UL CLASS="itemize"><LI CLASS="li-itemize">
1297
</BLOCKQUOTE><P>The <TT>ocamlmklib</TT> command takes three kinds of arguments:
1298
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
1840
1299
Caml source files and object files (<TT>.cmo</TT>, <TT>.cmx</TT>, <TT>.ml</TT>)
1841
1300
comprising the Caml part of the library;
1842
<LI CLASS="li-itemize">C object files (<TT>.o</TT>, <TT>.a</TT>) comprising the C part of the
1301
</LI><LI CLASS="li-itemize">C object files (<TT>.o</TT>, <TT>.a</TT>) comprising the C part of the
1843
1302
library;
1844
<LI CLASS="li-itemize">Support libraries for the C part (<TT>-l</TT><I>lib</I>).
1845
</UL>
1303
</LI><LI CLASS="li-itemize">Support libraries for the C part (<TT>-l</TT><I>lib</I>).
1304
</LI></UL><P>
1846
1305
It generates the following outputs:
1847
<UL CLASS="itemize"><LI CLASS="li-itemize">
1306
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
1848
1307
A Caml bytecode library <TT>.cma</TT> incorporating the <TT>.cmo</TT> and
1849
1308
<TT>.ml</TT> Caml files given as arguments, and automatically referencing the
1850
1309
C library generated with the C object files.
1851
<LI CLASS="li-itemize">A Caml native-code library <TT>.cmxa</TT> incorporating the <TT>.cmx</TT> and
1310
</LI><LI CLASS="li-itemize">A Caml native-code library <TT>.cmxa</TT> incorporating the <TT>.cmx</TT> and
1852
1311
<TT>.ml</TT> Caml files given as arguments, and automatically referencing the
1853
1312
C library generated with the C object files.
1854
<LI CLASS="li-itemize">If dynamic linking is supported on the target platform, a
1313
</LI><LI CLASS="li-itemize">If dynamic linking is supported on the target platform, a
1855
1314
<TT>.so</TT> shared library built from the C object files given as arguments,
1856
1315
and automatically referencing the support libraries.
1857
<LI CLASS="li-itemize">A C static library <TT>.a</TT> built from the C object files.
1858
</UL>
1316
</LI><LI CLASS="li-itemize">A C static library <TT>.a</TT> built from the C object files.
1317
</LI></UL><P>
1859
1318
In addition, the following options are recognized:
1860
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
1861
<B><TT>-cclib</TT>, <TT>-ccopt</TT>, <TT>-I</TT>, <TT>-linkall</TT></B><DD CLASS="dd-description">
1319
</P><DL CLASS="description"><DT CLASS="dt-description">
1320
<B><TT>-cclib</TT>, <TT>-ccopt</TT>, <TT>-I</TT>, <TT>-linkall</TT></B></DT><DD CLASS="dd-description">
1862
1321
These options are passed as is to <TT>ocamlc</TT> or <TT>ocamlopt</TT>.
1863
1322
See the documentation of these commands.
1864
<DT CLASS="dt-description"><B><TT>-pthread</TT>, <TT>-rpath</TT>, <TT>-R</TT>, <TT>-Wl,-rpath</TT>, <TT>-Wl,-R</TT></B><DD CLASS="dd-description">
1323
</DD><DT CLASS="dt-description"><B><TT>-pthread</TT>, <TT>-rpath</TT>, <TT>-R</TT>, <TT>-Wl,-rpath</TT>, <TT>-Wl,-R</TT></B></DT><DD CLASS="dd-description">
1865
1324
These options are passed as is to the C compiler. Refer to the
1866
1325
documentation of the C compiler.
1867
<DT CLASS="dt-description"><TT><B>-custom</B></TT><DD CLASS="dd-description"> Force the construction of a statically linked library
1326
</DD><DT CLASS="dt-description"><TT><B>-custom</B></TT></DT><DD CLASS="dd-description"> Force the construction of a statically linked library
1868
1327
only, even if dynamic linking is supported.
1869
<DT CLASS="dt-description"><TT><B>-failsafe</B></TT><DD CLASS="dd-description"> Fall back to building a statically linked library
1328
</DD><DT CLASS="dt-description"><TT><B>-failsafe</B></TT></DT><DD CLASS="dd-description"> Fall back to building a statically linked library
1870
1329
if a problem occurs while building the shared library (e.g. some of
1871
1330
the support libraries are not available as shared libraries).
1872
<DT CLASS="dt-description"><B><TT>-L</TT><I>dir</I></B><DD CLASS="dd-description"> Add <I>dir</I> to the search path for support
1331
</DD><DT CLASS="dt-description"><B><TT>-L</TT><I>dir</I></B></DT><DD CLASS="dd-description"> Add <I>dir</I> to the search path for support
1873
1332
libraries (<TT>-l</TT><I>lib</I>).
1874
<DT CLASS="dt-description"><B><TT>-ocamlc</TT> <I>cmd</I></B><DD CLASS="dd-description"> Use <I>cmd</I> instead of <TT>ocamlc</TT> to call
1333
</DD><DT CLASS="dt-description"><B><TT>-ocamlc</TT> <I>cmd</I></B></DT><DD CLASS="dd-description"> Use <I>cmd</I> instead of <TT>ocamlc</TT> to call
1875
1334
the bytecode compiler.
1876
<DT CLASS="dt-description"><B><TT>-ocamlopt</TT> <I>cmd</I></B><DD CLASS="dd-description"> Use <I>cmd</I> instead of <TT>ocamlopt</TT> to call
1335
</DD><DT CLASS="dt-description"><B><TT>-ocamlopt</TT> <I>cmd</I></B></DT><DD CLASS="dd-description"> Use <I>cmd</I> instead of <TT>ocamlopt</TT> to call
1877
1336
the native-code compiler.
1878
<DT CLASS="dt-description"><B><TT>-o</TT> <I>output</I></B><DD CLASS="dd-description"> Set the name of the generated Caml library.
1337
</DD><DT CLASS="dt-description"><B><TT>-o</TT> <I>output</I></B></DT><DD CLASS="dd-description"> Set the name of the generated Caml library.
1879
1338
<TT>ocamlmklib</TT> will generate <I>output</I><TT>.cma</TT> and/or <I>output</I><TT>.cmxa</TT>.
1880
1339
If not specified, defaults to <TT>a</TT>.
1881
<DT CLASS="dt-description"><B><TT>-oc</TT> <I>outputc</I></B><DD CLASS="dd-description"> Set the name of the generated C library.
1340
</DD><DT CLASS="dt-description"><B><TT>-oc</TT> <I>outputc</I></B></DT><DD CLASS="dd-description"> Set the name of the generated C library.
1882
1341
<TT>ocamlmklib</TT> will generate <TT>lib</TT><I>outputc</I><TT>.so</TT> (if shared
1883
1342
libraries are supported) and <TT>lib</TT><I>outputc</I><TT>.a</TT>.
1884
1343
If not specified, defaults to the output name given with <TT>-o</TT>.
1885
</DL>
1886
1887
<H5 CLASS="paragraph">Example</H5> Consider a Caml interface to the standard <TT>libz</TT>
1344
</DD></DL><H5 CLASS="paragraph">Example</H5><P> Consider a Caml interface to the standard <TT>libz</TT>
1888
1345
C library for reading and writing compressed files. Assume this
1889
1346
library resides in <TT>/usr/local/zlib</TT>. This interface is
1890
1347
composed of a Caml part <TT>zip.cmo</TT>/<TT>zip.cmx</TT> and a C part <TT>zipstubs.o</TT>
1891
1348
containing the stub code around the <TT>libz</TT> entry points. The
1892
1349
following command builds the Caml libraries <TT>zip.cma</TT> and <TT>zip.cmxa</TT>,
1893
1350
as well as the companion C libraries <TT>dllzip.so</TT> and <TT>libzip.a</TT>:
1894
<PRE CLASS="verbatim">
1895
ocamlmklib -o zip zip.cmo zip.cmx zipstubs.o -lz -L/usr/local/zlib
1896
</PRE>If shared libraries are supported, this performs the following
1351
</P><PRE CLASS="verbatim">ocamlmklib -o zip zip.cmo zip.cmx zipstubs.o -lz -L/usr/local/zlib
1352
</PRE><P>If shared libraries are supported, this performs the following
1897
1353
commands:
1898
<PRE CLASS="verbatim">
1899
ocamlc -a -o zip.cma zip.cmo -dllib -lzip \
1354
</P><PRE CLASS="verbatim">ocamlc -a -o zip.cma zip.cmo -dllib -lzip \
1900
1355
-cclib -lzip -cclib -lz -ccopt -L/usr/local/zlib
1901
1356
ocamlopt -a -o zip.cmxa zip.cmx -cclib -lzip \
1902
1357
-cclib -lzip -cclib -lz -ccopt -L/usr/local/zlib
1903
1358
gcc -shared -o dllzip.so zipstubs.o -lz -L/usr/local/zlib
1904
1359
ar rc libzip.a zipstubs.o
1905
</PRE>If shared libraries are not supported, the following commands are
1360
</PRE><P>If shared libraries are not supported, the following commands are
1906
1361
performed instead:
1907
<PRE CLASS="verbatim">
1908
ocamlc -a -custom -o zip.cma zip.cmo -cclib -lzip \
1362
</P><PRE CLASS="verbatim">ocamlc -a -custom -o zip.cma zip.cmo -cclib -lzip \
1909
1363
-cclib -lz -ccopt -L/usr/local/zlib
1910
1364
ocamlopt -a -o zip.cmxa zip.cmx -lzip \
1911
1365
-cclib -lz -ccopt -L/usr/local/zlib
1912
1366
ar rc libzip.a zipstubs.o
1913
</PRE>Instead of building simultaneously the bytecode library, the
1367
</PRE><P>Instead of building simultaneously the bytecode library, the
1914
1368
native-code library and the C libraries, <TT>ocamlmklib</TT> can be called
1915
1369
three times to build each separately. Thus,
1916
<PRE CLASS="verbatim">
1917
ocamlmklib -o zip zip.cmo -lz -L/usr/local/zlib
1918
</PRE>builds the bytecode library <TT>zip.cma</TT>, and
1919
<PRE CLASS="verbatim">
1920
ocamlmklib -o zip zip.cmx -lz -L/usr/local/zlib
1921
</PRE>builds the native-code library <TT>zip.cmxa</TT>, and
1922
<PRE CLASS="verbatim">
1923
ocamlmklib -o zip zipstubs.o -lz -L/usr/local/zlib
1924
</PRE>builds the C libraries <TT>dllzip.so</TT> and <TT>libzip.a</TT>. Notice that the
1370
</P><PRE CLASS="verbatim">ocamlmklib -o zip zip.cmo -lz -L/usr/local/zlib
1371
</PRE><P>builds the bytecode library <TT>zip.cma</TT>, and
1372
</P><PRE CLASS="verbatim">ocamlmklib -o zip zip.cmx -lz -L/usr/local/zlib
1373
</PRE><P>builds the native-code library <TT>zip.cmxa</TT>, and
1374
</P><PRE CLASS="verbatim">ocamlmklib -o zip zipstubs.o -lz -L/usr/local/zlib
1375
</PRE><P>builds the C libraries <TT>dllzip.so</TT> and <TT>libzip.a</TT>. Notice that the
1925
1376
support libraries (<TT>-lz</TT>) and the corresponding options
1926
1377
(<TT>-L/usr/local/zlib</TT>) must be given on all three invocations of <TT>ocamlmklib</TT>,
1927
1378
because they are needed at different times depending on whether shared
1928
libraries are supported.<BR>
1929
<BR>
1930
<HR>
1931
<A HREF="manual031.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
1932
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
1933
<A HREF="manual033.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
1379
libraries are supported.</P><HR>
1380
<A HREF="manual031.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
1381
<A HREF="index.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
1382
<A HREF="manual033.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
1934
1383
</BODY>
1935
1384
</HTML>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1