From 73345a6e022b7f0bc7cf6e63652af2abfeef0730 Mon Sep 17 00:00:00 2001 From: Xavier Leroy Date: Fri, 5 Mar 1999 13:04:59 +0000 Subject: [PATCH] MAJ pour release 2.02 git-svn-id: http://caml.inria.fr/svn/ocamldoc/trunk@9810 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02 --- manual/manual/Makefile | 1 + manual/manual/cmds/intf-c.etex | 106 ++++++++++++++++++++++++++++- manual/manual/library/Makefile | 3 +- manual/manual/library/stdlib.etex | 4 +- manual/manual/macros.tex | 4 ++ manual/manual/manual.htex | 2 +- manual/manual/pdfmanual.tex | 6 +- manual/manual/refman/modtypes.etex | 11 +++ manual/tools/htmlcut | 37 +++++++--- manual/tools/latexmacros.ml | 7 +- manual/tools/latexscan.mll | 4 +- manual/tools/transf.mll | 2 +- 12 files changed, 167 insertions(+), 20 deletions(-) diff --git a/manual/manual/Makefile b/manual/manual/Makefile index 7bb29790b..9e76671bb 100644 --- a/manual/manual/Makefile +++ b/manual/manual/Makefile @@ -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: diff --git a/manual/manual/cmds/intf-c.etex b/manual/manual/cmds/intf-c.etex index 4164658b4..4d36c2be0 100644 --- a/manual/manual/cmds/intf-c.etex +++ b/manual/manual/cmds/intf-c.etex @@ -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 diff --git a/manual/manual/library/Makefile b/manual/manual/library/Makefile index b62696473..c27a8cceb 100644 --- a/manual/manual/library/Makefile +++ b/manual/manual/library/Makefile @@ -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 \ diff --git a/manual/manual/library/stdlib.etex b/manual/manual/library/stdlib.etex index 9fc1517a7..66153c60d 100644 --- a/manual/manual/library/stdlib.etex +++ b/manual/manual/library/stdlib.etex @@ -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 diff --git a/manual/manual/macros.tex b/manual/manual/macros.tex index 095a8e392..fac400cdc 100644 --- a/manual/manual/macros.tex +++ b/manual/manual/macros.tex @@ -211,6 +211,10 @@ \def\pdfchapter{\pdfchapterfold{0}} +%%% Pour camlidl + +\def\transl#1{$[\![\mbox{#1}]\!]$} + %%% Fin des hacks \makeatother diff --git a/manual/manual/manual.htex b/manual/manual/manual.htex index b11a10d62..156ae986e 100644 --- a/manual/manual/manual.htex +++ b/manual/manual/manual.htex @@ -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} diff --git a/manual/manual/pdfmanual.tex b/manual/manual/pdfmanual.tex index 1e361a5f8..446ab95f7 100644 --- a/manual/manual/pdfmanual.tex +++ b/manual/manual/pdfmanual.tex @@ -1,7 +1,7 @@ %\pdfoutput=1 -%\pdfpagewidth=21cm -%\pdfpageheight=11in -%\pdfcompresslevel=7 +\pdfpagewidth=21cm +\pdfpageheight=11in +\pdfcompresslevel=7 \documentclass[11pt]{book} diff --git a/manual/manual/refman/modtypes.etex b/manual/manual/refman/modtypes.etex index a940149cb..0defc9a28 100644 --- a/manual/manual/refman/modtypes.etex +++ b/manual/manual/refman/modtypes.etex @@ -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}} diff --git a/manual/tools/htmlcut b/manual/tools/htmlcut index 1735d5431..be079abb2 100755 --- a/manual/tools/htmlcut +++ b/manual/tools/htmlcut @@ -2,10 +2,29 @@ # Split an HTML file into smaller nodes. # Split at

headers and also at some

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() { - if (m|^(.*)|) { + if (m|^<$h0>(.*)|o) { $level0++; $currfile = "node" . ($level1 + 1) . ".html"; $lblnum = $level0; $uselabel = 0; } - if (m|^

(.*)

|) { + if (m|^<$h1>(.*)|o) { $level1++; $level2 = 0; $currfile = "node$level1.html"; $lblnum = $level1; $uselabel = 1; } - if (m|^

(.*)

|) { + if (m|^<$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() { - if (m|^(.*)|) { + if (m|^<$h0>(.*)|o) { if ($level2 > 0) { print FILE1 "\n"; } select(STDOUT); if ($level1 >= 1) { print ""; } - print "

$1

\n"; + print "<$h2>$1\n"; if ($level1 >= 1) { print "\n"; } $level1++; $level2 = 0; @@ -70,7 +89,7 @@ while() { select(FILE1); &print_title($1); } - if ($split2[$level1] && m|^

(.*)

|) { + if ($split2[$level1] && m|^<$h2>(.*)|o) { $level2++; select(FILE1); if ($level2 == 1) { print "