16

Is there any documentation about the Obj module? I could only find a list of functions without any description...

(BTW: I know these are low-level functions not meant to be generally used)

Mauricio Scheffer
  • 98,863
  • 23
  • 192
  • 275

3 Answers3

20

Yes, it is clearly undocumented on purpose. For five uses of Obj I see (or write myself, which is more disturbing), two of them are unjustified, two of them are a way to avoid a cleaner design change that would be useful anyway, and one of them is a genuine "good solution" to a complicated problem.

Obj only expose type-breaking operations that allow to explore and manipulate the runtime representation of OCaml data. You don't need documentation for these functions, they're obvious, but you need to know about OCaml data representation (I learned it using this document, but the ocaml manual also documents it), and if you want to hack into it you should know about the runtime to know what's safe and what isn't. As a general rule: don't.

Here are a few legitimate uses of Obj:

  • when compiling Coq programs to OCaml programs; the Coq type system being more powerful, it can type things that OCaml would reject, hence the Coq->Ocaml translator inserts Obj.magic calls to force OCaml into accepting its output.

  • when encoding GADTs in OCaml 3.x, which didn't support it -- they were added to 4.00. There is one encoding with module-level equality and functors (see this post or this work), but the more common one (used in the menhir parser generator which is a great replacement for ocamlyacc, see this paper (PDF)) uses Obj.magic

  • when marshalling data using some kind of (home-made) runtime type information. The Marshal module of OCaml is already not type-safe (for obvious reason), and if you need a different kind of marshalling in a different context (eg. to/from queries and results for a SQL server, as I did in my macaque project) you will need some kind of unsafe cast.

gasche
  • 31,259
  • 3
  • 78
  • 100
  • 10
    I understand that its use is discouraged and the reasons behind it, but IMHO that's not reason enough not to document it... – Mauricio Scheffer May 19 '11 at 12:31
  • "GADTs in current OCaml, which doesn't support it" refers to versions prior to 4.00, no? – anol Nov 09 '12 at 10:55
  • dhekir: indeed, this post was written before the last release. I'll edit the message with a future-proof version bound, thanks for the notice. – gasche Nov 09 '12 at 12:58
  • 1
    Another legitimate use: the `is_block`, `is_int`, `tag`, `size`, `field`, etc. functions provide a kind of *reflection interface* for OCaml, which are useful to e.g. write a runtime pretty printer that prints a value of any type, saving you from having to make one for every type. – newacct Nov 09 '12 at 19:35
  • @newacct I don't think this is a legitimate use, there are correct ways to pretty-print data (essentially, build the type-correct printers explicitly). The way you suggest seems easy and is quick to implement, but it doesn't really work well in the end and should be avoided. Exactly the kind of things I don't particularly want to encourage beginners to use. – gasche Nov 09 '12 at 22:01
  • In addition to `Obj.magic`, Coq extracted code uses some other `Obj` constructs, apparently to enforce forms of lazy evaluation in the presence of arguments from `Prop` types. – David Monniaux Mar 27 '13 at 17:39
10

The module Obj basically deals with the structure and interpretation of OCaml values in the heap. If you want to understand what this means you must read chapter 18 of the OCaml manual, "Interfacing C with Objective Caml".

The reason why this is undocumented is twofold: first of all, the functions are horribly unsafe. There is simply no total function with type 'a -> 'b so you can see that Obj.magic must do quite a bit of it if it is to return anything at all. In fact it is just a hole into the type system, a "license to kill" it. Second, the module allows you to peek and poke into the heap at will, in effect providing the moral equivalent of C's pointers to void. This together with unrestricted casts lets you do whatever you want from OCaml.

There are legitimate uses for Obj, though. I count more than 100 occurrences of Obj.magic in the sources, most notably in the code for Printf and Scanf. Another legitimate use is for tail-recursive list operations, provided you can prove that the code is type-safe and thread-safe.

If you don't mind the self-plugs, here is an example of an unsafe operation that is wrapped in a safe interface, together with a proof ("Since at each step the cons cell is fresh…") that it is indeed safe, and here is another.

3

You won't find any documentation for these functions. If you want to use them, and I won't repeat that this is discouraged, you have to read and understand their implementation. But as I remember, three of them are implemented as "%identity", so this is not as hard as it seems.

Pascal Cuoq
  • 79,187
  • 7
  • 161
  • 281
  • 2
    I don't get why someone can't just describe what each of these functions does. BTW I'm not trying to use them but understand their role in some code I'm reading. – Mauricio Scheffer May 19 '11 at 00:24
  • 2
    @Mauricio That hypothetical benevolent writer would do well to start with the OCaml tutorial, which is missing more sorely than documentation for module Obj. This said, if you told us which Obj functions you are encountering, we might be able to summarize their applications roughly — keeping in mind that understanding the runtime is a prerequisite for really understanding what effects these functions may have. – Pascal Cuoq May 19 '11 at 00:42
  • @Pascal: thanks, for a moment I thought it was undocumented *on purpose*! :) – Mauricio Scheffer May 19 '11 at 03:52
  • @Pascal: I think I can extrapolate from these F# docs: http://research.microsoft.com/en-us/um/cambridge/projects/fsharp/manual/fsharp.powerpack/microsoft.fsharp.compatibility.ocaml.obj.html – Mauricio Scheffer May 19 '11 at 04:07
  • 3
    @Mauricio: it *is* undocumented on purpose. –  May 19 '11 at 12:21
  • @Matías: I understand that its use is discouraged and the reasons behind it, but IMHO that's not reason enough not to document it... – Mauricio Scheffer May 19 '11 at 12:31
  • 4
    Straight from the horse's mouth: [Repeat after me: "Obj.magic is not part of the OCaml language"](http://article.gmane.org/gmane.comp.lang.caml.general/47389). –  May 19 '11 at 12:44
  • 1
    @Matías: thanks for the reference. Still, couldn't the same thing be said about Haskell's unsafePerformIO? Yet it's perfectly documented: http://www.haskell.org/ghc/docs/7.0.3/html/libraries/base-4.3.1.0/System-IO-Unsafe.html http://www.haskell.org/haskellwiki/Top_level_mutable_state – Mauricio Scheffer May 19 '11 at 13:05
  • Actually unsafePerformIO is part of the Haskell 2010 standard, as the FFI needs it. – Demi Aug 18 '15 at 15:18
  • Even Haskell's unsafeCoerce is documented. – Demi Oct 14 '15 at 16:00