Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0005415OCamlOCaml documentationpublic2011-12-05 09:352013-08-31 12:48
ReporterChristophe Troestler 
Assigned Toxleroy 
PrioritynormalSeverityminorReproducibilityN/A
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version3.12.1 
Target VersionFixed in Version4.00.0+dev 
Summary0005415: Obtaining an OCaml closure from C
DescriptionThe manual, section 18.7.2, describes a way to obtain an OCaml closure using Callback.register. However, this is not always desirable. Take the example of a C function, say [root], finding a root of a function [f: float -> float]. Passing [f] through Callback.register means that the code will not work when using [root] from different threads. More important even is that [f] cannot call [root] (which is sometimes the case)! Therefore, it would be nice if the manual were saying that an alternative way, as the one described below, is guaranteed to work.

CAMLexport value root(value vf, value x)
{
  CAMLparam2(vf, x);
  value *closure_f = &vf;

...
  caml_callback(*closure_f, x);
...
}
Additional InformationP.S. Of course one could create a new string on each call of [root], appending a number to a given prefix. This is both heavy and impractical given the poor C string handling library.
TagsNo tags attached.
Attached Filestxt file icon manual032.txt [^] (1,042 bytes) 2011-12-11 11:25 [Show Content]
txt file icon manual032-2.txt [^] (1,031 bytes) 2011-12-13 11:11 [Show Content]

- Relationships

-  Notes
(0006222)
Christophe Troestler (reporter)
2011-12-10 18:43

I forgot to mention that, if the technical side is confirmed, I can try to write a paragraph to include in the manual.
(0006225)
lefessan (developer)
2011-12-11 00:04

You can simplify this code to:

value root(value vf, value x)
{
  CAMLparam2(vf, x);
...
  caml_callback(vf, x);
...
}

I thought it was clear in the manual that caml_callback(...) can be used on functional values received from OCaml, i.e. closures, but maybe adding another example can make things easier to understand.
(0006226)
Christophe Troestler (reporter)
2011-12-11 01:26
edited on: 2011-12-11 01:28

It was not really clear because there is a section "Registering Caml closures for use in C functions" that starts with "The main difficulty with the callback functions described above is obtaining a closure to the Caml function to be called." followed by a description of how to do it — implying that there is no other way.

(0006227)
Christophe Troestler (reporter)
2011-12-11 11:25

Uploaded a proposal to modify section 18.7.2 of the manual.
(0006257)
gasche (developer)
2011-12-13 01:38

Nitpicking: "There are two ways to obtain closures of OCaml functions.", rather than "for obtaining ...".

I also found the manual quite clear. I'm not sure your proposed modification would make it clearer (in section 18.7.2 you describe "two ways", but only the second is actually relevant to the subsection, as the other needs no registration mechanism).

I believe the documentation could be better clarified by simply providing an example in section 18.7.1 (Applying Caml closures from C). Why not the example you suggest -- though I personally find it a bit strange that you export as `(float -> float) -> float -> float` a function that seems polymorphic.
(0006260)
Christophe Troestler (reporter)
2011-12-13 11:22

I have taken your remarks into account in the new version I uploaded. I supposed I put too much emphasis on "The main difficulty..." which was for me casting some doubt (especially for newcomers) whether the simple way of obtaining a closure is officially supported — after all, it implies we do not really need the registration mechanism when the main program is in OCaml.
(0007186)
xleroy (administrator)
2012-03-27 10:31

Second patch integrated into the manual, will go in 4.00.

- Issue History
Date Modified Username Field Change
2011-12-05 09:35 Christophe Troestler New Issue
2011-12-10 18:43 Christophe Troestler Note Added: 0006222
2011-12-11 00:04 lefessan Note Added: 0006225
2011-12-11 01:26 Christophe Troestler Note Added: 0006226
2011-12-11 01:28 Christophe Troestler Note Edited: 0006226 View Revisions
2011-12-11 11:25 Christophe Troestler File Added: manual032.txt
2011-12-11 11:25 Christophe Troestler Note Added: 0006227
2011-12-13 01:38 gasche Note Added: 0006257
2011-12-13 11:11 Christophe Troestler File Added: manual032-2.txt
2011-12-13 11:22 Christophe Troestler Note Added: 0006260
2012-03-26 15:30 xleroy Assigned To => xleroy
2012-03-26 15:30 xleroy Status new => assigned
2012-03-27 10:31 xleroy Note Added: 0007186
2012-03-27 10:31 xleroy Status assigned => resolved
2012-03-27 10:31 xleroy Resolution open => fixed
2012-03-27 10:31 xleroy Fixed in Version => 4.00.0+dev
2013-08-31 12:48 xleroy Status resolved => closed


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker