MAJ pour release 2.02
git-svn-id: http://caml.inria.fr/svn/ocamldoc/trunk@9810 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02master
Xavier Leroy
parent
cd21bd87f4
commit
73345a6e02
|
|
@ -64,6 +64,7 @@ release:
|
|||
# cp texstuff/plaintext.txt $(RELEASE)refman.txt
|
||||
# cp texstuff/plaintext.ipr $(RELEASE)refman.prn
|
||||
tar cf - htmlman/*.* | gzip > $(RELEASE)refman.html.tar.gz
|
||||
zip -8 $(RELEASE)refman.html.zip htmlman/*.*
|
||||
cp texstuff/pdfmanual.pdf $(RELEASE)refman.pdf
|
||||
|
||||
.SUFFIXES:
|
||||
|
|
|
|||
|
|
@ -38,6 +38,28 @@ The latter is slightly more efficient, as it allows clients of the
|
|||
module to call directly the C function instead of going through the
|
||||
corresponding Caml function.
|
||||
|
||||
The arity (number of arguments) of a primitive is automatically
|
||||
determined from its Caml type in the "external" declaration, by
|
||||
counting the number of function arrows in the type. For instance,
|
||||
"input" above has arity 4, and the "input" C function is called with
|
||||
four arguments. Similarly,
|
||||
\begin{verbatim}
|
||||
external input2 : in_channel * string * int * int -> int = "input2"
|
||||
\end{verbatim}
|
||||
has arity 1, and the "input2" C function receives one argument (which
|
||||
is a quadruple of Caml values).
|
||||
|
||||
Type abbreviations are not expanded when determining the arity of a
|
||||
primitive. For instance,
|
||||
\begin{verbatim}
|
||||
type int_endo = int -> int
|
||||
external f : int_endo -> int_endo = "f"
|
||||
external g : (int -> int) -> (int -> int) = "f"
|
||||
\end{verbatim}
|
||||
"f" has arity 1, but "g" has arity 2. This allows a primitive to
|
||||
return a functional value (as in the "f" example above): just remember
|
||||
to name the functional return type in a type abbreviation.
|
||||
|
||||
\subsection{Implementing primitives}
|
||||
|
||||
User primitives with arity $n \leq 5$ are implemented by C functions
|
||||
|
|
@ -382,7 +404,7 @@ and false if it is an immediate integer.
|
|||
truth value of the C integer \var{x}.
|
||||
\item "Bool_val("\var{v}")" returns 0 if \var{v} is the Caml boolean
|
||||
"false", 1 if \var{v} is "true".
|
||||
\item "Val_true", "Val_false" represent to Caml booleans "true" and "false".
|
||||
\item "Val_true", "Val_false" represent the Caml booleans "true" and "false".
|
||||
\end{itemize}
|
||||
|
||||
\subsection{Accessing blocks}
|
||||
|
|
@ -447,7 +469,7 @@ fields of the block are initialized with a valid value in order to
|
|||
satisfy the GC constraints.
|
||||
\item
|
||||
"alloc_tuple("\var{n}")" returns a fresh block of size
|
||||
$n \leq \hbox{"Max_young_wosize"}$ words, with tag 0.
|
||||
\var{n} words, with tag 0.
|
||||
\item
|
||||
"alloc_string("\var{n}")" returns a string value of length \var{n} characters.
|
||||
The string initially contains garbage.
|
||||
|
|
@ -506,6 +528,54 @@ with legal values (using the "initialize" function described below)
|
|||
before the next allocation.
|
||||
\end{itemize}
|
||||
|
||||
\subsection{Finalized blocks}
|
||||
|
||||
Blocks with tag "Final_tag" have an attached C finalization function
|
||||
that is called when the block becomes unreachable and is about to be
|
||||
reclaimed. The finalization function occupies the first word of the
|
||||
allocated block; the remaining words can contain arbitrary raw data
|
||||
(but not Caml pointers, since "Final_tag" is greater than
|
||||
"No_scan_tag".
|
||||
|
||||
Finalized blocks must be allocated via the "alloc_final" function.
|
||||
"alloc_final("\var{n}", "\var{f}", "\var{used}", "\var{max}")"
|
||||
returns a fresh finalized block of size \var{n} words, with
|
||||
finalization function \var{f}.
|
||||
|
||||
The two parameters \var{used} and \var{max} are used to control the
|
||||
speed of garbage collection when the finalized object contains
|
||||
pointers to out-of-heap resources. Generally speaking, the
|
||||
Caml incremental major collector adjusts its speed relative to the
|
||||
allocation rate of the program. The faster the program allocates, the
|
||||
harder the GC works in order to reclaim quickly unreachable blocks
|
||||
and avoid having large amount of ``floating garbage'' (unreferenced
|
||||
objects that the GC has not yet collected).
|
||||
|
||||
Normally, the allocation rate is measured by counting the in-heap size
|
||||
of allocated blocks. However, it often happens that finalized
|
||||
objects contain pointers to out-of-heap memory blocks and other resources
|
||||
(such as file descriptors, X Windows bitmaps, etc.). For those
|
||||
blocks, the in-heap size of blocks is not a good measure of the
|
||||
quantity of resources allocated by the program.
|
||||
|
||||
The two arguments \var{used} and \var{max} give the GC an idea of how
|
||||
much out-of-heap resources are consumed by the finalized block
|
||||
being allocated: you give the amount of resources allocated to this
|
||||
object as parameter \var{used}, and the maximum amount that you want
|
||||
to see in floating garbage as parameter \var{max}. The units are
|
||||
arbitrary: the GC cares only about the ratio $\var{used} / \var{max}$.
|
||||
|
||||
For instance, if you are allocating a finalized block holding an X
|
||||
Windows bitmap of \var{w} by \var{h} pixels, and you'd rather not
|
||||
have more than 1 mega-pixels of unreclaimed bitmaps, specify
|
||||
$\var{used} = \var{w} * \var{h}$ and $\var{max} = 1000000$.
|
||||
|
||||
If your finalized blocks contain no pointers to out-of-heap resources,
|
||||
or if the previous discussion made little sense to you, just take
|
||||
$\var{used} = 0$ and $\var{max} = 1$. But if you later find that the
|
||||
finalization functions are not called ``often enough'', consider
|
||||
increasing the $\var{used} / \var{max}$ ratio.
|
||||
|
||||
\subsection{Raising exceptions} \label{s:c-exceptions}
|
||||
|
||||
Two functions are provided to raise two standard exceptions:
|
||||
|
|
@ -818,6 +888,8 @@ the value \var{a} and return the value returned by~\var{f}.
|
|||
\var{a} and \var{b}.
|
||||
\item "callback3("\var{f, a, b, c}")" applies the functional value \var{f}
|
||||
(a curried Caml function with three arguments) to \var{a}, \var{b} and \var{c}.
|
||||
\item "callbackN("\var{f, n, args}")" applies the functional value \var{f}
|
||||
to the \var{n} arguments contained in the array of values \var{args}.
|
||||
\end{itemize}
|
||||
If the function \var{f} does not return, but raises an exception that
|
||||
escapes the scope of the application, then this exception is
|
||||
|
|
@ -827,6 +899,18 @@ calls back a Caml function \var{h} that raises a stray exception, then the
|
|||
execution of \var{g} is interrupted and the exception is propagated back
|
||||
into \var{f}.
|
||||
|
||||
If the C code wishes to catch exceptions escaping the Caml function,
|
||||
it can use the functions "callback_exn", "callback2_exn",
|
||||
"callback3_exn", "callbackN_exn". These functions take the same
|
||||
arguments as their non-"_exn" counterparts, but catch escaping
|
||||
exceptions and return them to the C code. The return value \var{v} of the
|
||||
"callback*_exn" functions must be tested with the macro
|
||||
"Is_exception_result("\var{v}")". If the macro returns ``false'', no
|
||||
exception occured, and \var{v} is the value returned by the Caml
|
||||
function. If "Is_exception_result("\var{v}")" returns ``true'',
|
||||
an exception escaped, and its value (the exception descriptor) can be
|
||||
recovered using "Extract_exception("\var{v}")".
|
||||
|
||||
\subsection{Registering Caml closures for use in C functions}
|
||||
|
||||
The main difficulty with the "callback" functions described above is
|
||||
|
|
@ -965,6 +1049,24 @@ code for all Caml modules on the command-line, as well as the Caml
|
|||
startup code. Initialization is performed by calling "caml_startup" as
|
||||
in the case of the bytecode compiler.
|
||||
|
||||
For the final linking phase, in addition to the object file produced
|
||||
by "-output-obj", you will have to provide the Objective Caml runtime
|
||||
library ("libcamlrun.a" for bytecode, "libasmrun.a" for native-code),
|
||||
as well as all C libraries that are required by the Caml libraries
|
||||
used. For instance, assume the Caml part of your program uses the
|
||||
Unix library. With "ocamlc", you should do:
|
||||
\begin{alltt}
|
||||
ocamlc -output-obj -o camlcode.o unix.cma {\it{other}} .cmo {\it{and}} .cma {\it{files}}
|
||||
cc -o myprog {\it{C objects and libraries}} \char92
|
||||
camlcode.o -L/usr/local/lib/ocaml -lunix -lcamlrun
|
||||
\end{alltt}
|
||||
With "ocamlopt", you should do:
|
||||
\begin{alltt}
|
||||
ocamlopt -output-obj -o camlcode.o unix.cmxa {\it{other}} .cmx {\it{and}} .cmxa {\it{files}}
|
||||
cc -o myprog {\it{C objects and libraries}} \char92
|
||||
camlcode.o -L/usr/local/lib/ocaml -lunix -lasmrun
|
||||
\end{alltt}
|
||||
|
||||
\paragraph{Warning:} On some ports, special options are required on the final
|
||||
linking phase that links together the object file produced by the
|
||||
"-output-obj" option and the remainder of the program. Those options
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@ STDLIB_INTF=arg.tex array.tex char.tex digest.tex filename.tex format.tex \
|
|||
gc.tex genlex.tex hashtbl.tex lazy.tex lexing.tex list.tex map.tex \
|
||||
marshal.tex oo.tex \
|
||||
parsing.tex printexc.tex printf.tex queue.tex random.tex set.tex sort.tex \
|
||||
stack.tex stream.tex string.tex sys.tex weak.tex callback.tex lazy.tex
|
||||
stack.tex stream.tex string.tex sys.tex weak.tex callback.tex lazy.tex \
|
||||
buffer.tex
|
||||
|
||||
OTHERLIB_INTF=unix.tex str.tex num.tex arithstatus.tex graphics.tex \
|
||||
thread.tex mutex.tex condition.tex event.tex threadUnix.tex \
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
\chapter{The standard library}
|
||||
\pdfchapterfold{-28}{The standard library}
|
||||
\pdfchapterfold{-29}{The standard library}
|
||||
|
||||
This chapter describes the functions provided by the Caml Light
|
||||
standard library. The modules from the standard library are
|
||||
|
|
@ -45,6 +45,7 @@ Here is a short listing, by theme, of the standard library modules.
|
|||
"Oo" & p.~\pageref{s:Oo} & useful functions on objects \\
|
||||
"Stack" & p.~\pageref{s:Stack} & last-in first-out stacks \\
|
||||
"Queue" & p.~\pageref{s:Queue} & first-in first-out queues \\
|
||||
"Buffer" & p.~\pageref{s:Buffer} & string buffers that grow on demand \\
|
||||
"Lazy" & p.~\pageref{s:Lazy} & delayed evaluation \\
|
||||
"Weak" & p.~\pageref{s:Weak} & references that don't prevent objects from being garbage-collected \\
|
||||
\end{tabular}
|
||||
|
|
@ -78,6 +79,7 @@ be called from C \\
|
|||
\begin{library}
|
||||
\input arg.tex
|
||||
\input array.tex
|
||||
\input buffer.tex
|
||||
\input callback.tex
|
||||
\input char.tex
|
||||
\input digest.tex
|
||||
|
|
|
|||
|
|
@ -211,6 +211,10 @@
|
|||
|
||||
\def\pdfchapter{\pdfchapterfold{0}}
|
||||
|
||||
%%% Pour camlidl
|
||||
|
||||
\def\transl#1{$[\![\mbox{#1}]\!]$}
|
||||
|
||||
%%% Fin des hacks
|
||||
|
||||
\makeatother
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
|
||||
(with Didier Rémy, Jérôme Vouillon and Damien Doligez)
|
||||
|
||||
Copyright \copyright\ 1998 Institut National de Recherche en Informatique et
|
||||
Copyright \copyright\ 1999 Institut National de Recherche en Informatique et
|
||||
Automatique
|
||||
|
||||
\begin{rawhtml}
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
%\pdfoutput=1
|
||||
%\pdfpagewidth=21cm
|
||||
%\pdfpageheight=11in
|
||||
%\pdfcompresslevel=7
|
||||
\pdfpagewidth=21cm
|
||||
\pdfpageheight=11in
|
||||
\pdfcompresslevel=7
|
||||
|
||||
\documentclass[11pt]{book}
|
||||
|
||||
|
|
|
|||
|
|
@ -36,6 +36,7 @@ specification:
|
|||
| 'module' 'type' modtype-name
|
||||
| 'module' 'type' modtype-name '=' module-type
|
||||
| 'open' module-path
|
||||
| 'include' modtype-path
|
||||
;
|
||||
constraint:
|
||||
'type' [type-parameters] typeconstr '=' typexp
|
||||
|
|
@ -211,6 +212,16 @@ of the signature, allowing components of the module denoted by
|
|||
path accesses @module-path '.' name@. The scope of the "open"
|
||||
stops at the end of the signature expression.
|
||||
|
||||
\subsubsection{Including a signature}
|
||||
|
||||
\ikwd{include\@\texttt{include}}
|
||||
|
||||
The expression @'include' modtype-path@ in a signature performs textual
|
||||
inclusion of the components of the signature denoted by @modtype-path@.
|
||||
It behaves as if the components of the included signature were copied
|
||||
at the location of the @'include'@. The @modtype-path@ argument must
|
||||
refer to a module type that is a signature,
|
||||
|
||||
\subsection{Functor types}
|
||||
|
||||
\ikwd{functor\@\texttt{functor}}
|
||||
|
|
|
|||
|
|
@ -2,10 +2,29 @@
|
|||
# Split an HTML file into smaller nodes.
|
||||
# Split at <H1> headers and also at some <H2> headers.
|
||||
|
||||
while ($ARGV[0] =~ /^-([0-9]+)$/) {
|
||||
$split2[$1] = 1;
|
||||
$h0 = "H0";
|
||||
$h1 = "H1";
|
||||
$h2 = "H2";
|
||||
|
||||
# Parse options
|
||||
|
||||
option:
|
||||
while(1) {
|
||||
$_ = $ARGV[0];
|
||||
if (/^-([0-9]+)$/) {
|
||||
$split2[$1] = 1;
|
||||
}
|
||||
elsif (/^-article/) {
|
||||
$h0 = "H1";
|
||||
$h1 = "H2";
|
||||
$h2 = "H3";
|
||||
}
|
||||
else {
|
||||
last option;
|
||||
}
|
||||
shift(@ARGV);
|
||||
}
|
||||
|
||||
$infile = $ARGV[0];
|
||||
|
||||
# Find URL's for the links
|
||||
|
|
@ -15,20 +34,20 @@ $level1 = 0;
|
|||
$uselabel = 1;
|
||||
open(INPUT, $infile);
|
||||
while(<INPUT>) {
|
||||
if (m|^<H0>(.*)</H0>|) {
|
||||
if (m|^<$h0>(.*)</$h0>|o) {
|
||||
$level0++;
|
||||
$currfile = "node" . ($level1 + 1) . ".html";
|
||||
$lblnum = $level0;
|
||||
$uselabel = 0;
|
||||
}
|
||||
if (m|^<H1>(.*)</H1>|) {
|
||||
if (m|^<$h1>(.*)</$h1>|o) {
|
||||
$level1++;
|
||||
$level2 = 0;
|
||||
$currfile = "node$level1.html";
|
||||
$lblnum = $level1;
|
||||
$uselabel = 1;
|
||||
}
|
||||
if (m|^<H2>(.*)</H2>|) {
|
||||
if (m|^<$h2>(.*)</$h2>|o) {
|
||||
$level2++;
|
||||
if ($split2[$level1]) { $currfile = "node$level1.$level2.html"; }
|
||||
$lblnum = "$level1.$level2";
|
||||
|
|
@ -51,15 +70,15 @@ sub set_url {
|
|||
$level1 = 0;
|
||||
open(INPUT, $infile);
|
||||
while(<INPUT>) {
|
||||
if (m|^<H0>(.*)</H0>|) {
|
||||
if (m|^<$h0>(.*)</$h0>|o) {
|
||||
if ($level2 > 0) { print FILE1 "</UL>\n"; }
|
||||
select(STDOUT);
|
||||
if ($level1 >= 1) { print "</UL>"; }
|
||||
print "<H2>$1</H2>\n";
|
||||
print "<$h2>$1</$h2>\n";
|
||||
if ($level1 >= 1) { print "<UL>"; }
|
||||
next;
|
||||
}
|
||||
if (m|^<H1>(.*)</H1>|) {
|
||||
if (m|^<$h1>(.*)</$h1>|o) {
|
||||
if ($level2 > 0) { print FILE1 "</UL>\n"; }
|
||||
$level1++;
|
||||
$level2 = 0;
|
||||
|
|
@ -70,7 +89,7 @@ while(<INPUT>) {
|
|||
select(FILE1);
|
||||
&print_title($1);
|
||||
}
|
||||
if ($split2[$level1] && m|^<H2>(.*)</H2>|) {
|
||||
if ($split2[$level1] && m|^<$h2>(.*)</$h2>|o) {
|
||||
$level2++;
|
||||
select(FILE1);
|
||||
if ($level2 == 1) { print "<HR><BR><UL>\n"; }
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ def_macro "\\subsubsection"
|
|||
def_macro "\\subsubsection*"
|
||||
[Print "<H4>"; Print_arg; Print "</H4>\n"];
|
||||
def_macro "\\paragraph"
|
||||
[Print "<H5>"; Print_arg; Print "</H5>\n"];
|
||||
[Print "<B>"; Print_arg; Print "</B> \n"];
|
||||
def_macro "\\begin{alltt}" [Print "<pre>"];
|
||||
def_macro "\\end{alltt}" [Print "</pre>"];
|
||||
def_macro "\\begin{itemize}" [Print "<p><ul>"];
|
||||
|
|
@ -41,6 +41,10 @@ def_macro "\\begin{description}" [Print "<p><dl>"];
|
|||
def_macro "\\end{description}" [Print "</dl>"];
|
||||
def_macro "\\begin{center}" [Print "<blockquote>"];
|
||||
def_macro "\\end{center}" [Print "</blockquote>"];
|
||||
def_macro "\\begin{quote}" [Print "<blockquote>"];
|
||||
def_macro "\\end{quote}" [Print "</blockquote>"];
|
||||
def_macro "\\begin{quotation}" [Print "<blockquote>"];
|
||||
def_macro "\\end{quotation}" [Print "</blockquote>"];
|
||||
def_macro "\\smallskip" [];
|
||||
def_macro "\\medskip" [];
|
||||
def_macro "\\bigskip" [];
|
||||
|
|
@ -133,5 +137,6 @@ def_macro "\\event" [Print "<font color=\"red\">*</font>"];
|
|||
def_macro "\\pdfchapter" [Skip_arg];
|
||||
def_macro "\\pdfchapterfold" [Skip_arg; Skip_arg];
|
||||
def_macro "\\pdfsection" [Skip_arg];
|
||||
def_macro "\\transl" [Print "<"; Print_arg; Print ">"];
|
||||
();;
|
||||
|
||||
|
|
|
|||
|
|
@ -35,6 +35,8 @@ rule main = parse
|
|||
print_string "</i>"; main lexbuf }
|
||||
| "{\\bf" " "* { print_string "<b>"; upto `}` main lexbuf;
|
||||
print_string "</b>"; main lexbuf }
|
||||
| "{\\rm" " "* { print_string "<u>"; upto `}` main lexbuf;
|
||||
print_string "</u>"; main lexbuf }
|
||||
| "{\\tt" " "* { print_string "<tt>"; upto `}` main lexbuf;
|
||||
print_string "</tt>"; main lexbuf }
|
||||
| `"` { print_string "<tt>"; indoublequote lexbuf;
|
||||
|
|
@ -151,7 +153,7 @@ and latexonly = parse
|
|||
| _ { latexonly lexbuf }
|
||||
|
||||
and print_arg = parse
|
||||
"{" { upto `}` main lexbuf }
|
||||
[` ` `\n`] * "{" { upto `}` main lexbuf }
|
||||
| _ { print_char(get_lexeme_char lexbuf 0); rawhtml lexbuf }
|
||||
|
||||
and skip_arg = parse
|
||||
|
|
|
|||
|
|
@ -26,6 +26,7 @@ and syntax = parse
|
|||
| `"` {
|
||||
print_string "\\token{";
|
||||
indoublequote lexbuf }
|
||||
| "epsilon" { print_string "\\emptystring"; syntax lexbuf }
|
||||
| [`a`-`z``-`] + {
|
||||
print_string "\\nonterm{";
|
||||
print_string (get_lexeme lexbuf);
|
||||
|
|
@ -49,7 +50,6 @@ and syntax = parse
|
|||
| ":" { print_string "\\is "; syntax lexbuf }
|
||||
| "|" { print_string "\\alt "; syntax lexbuf }
|
||||
| ";" { print_string "\\sep "; syntax lexbuf }
|
||||
| "@" { print_string "\\emptystring"; syntax lexbuf }
|
||||
| _ {
|
||||
print_char (get_lexeme_char lexbuf 0);
|
||||
syntax lexbuf }
|
||||
|
|
|
|||
Loading…
Reference in New Issue