Download The Objective Caml system release 2.02 - The Caml language

Chapter 15. Interfacing C with Objective Caml
15.4.4
173
Allocating blocks
Simple interface
• Atom(t) returns an “atom” (zero-sized block) with tag t. Zero-sized blocks are preallocated
outside of the heap. It is incorrect to try and allocate a zero-sized block using the functions
below. For instance, Atom(0) represents the empty array.
• alloc(n, t) returns a fresh block of size n with tag t. If t is less than No_scan_tag, then
the fields of the block are initialized with a valid value in order to satisfy the GC constraints.
• alloc_tuple(n) returns a fresh block of size n words, with tag 0.
• alloc_string(n) returns a string value of length n characters. The string initially contains
garbage.
• copy_string(s) returns a string value containing a copy of the null-terminated C string s (a
char *).
• copy_double(d) returns a floating-point value initialized with the double d.
• alloc_array(f, a) allocates an array of values, calling function f over each element of the
input array a to transform it into a value. The array a is an array of pointers terminated
by the null pointer. The function f receives each pointer as argument, and returns a value.
The zero-tagged block returned by alloc_array(f, a) is filled with the values returned by
the successive calls to f. (This function must not be used to build an array of floating-point
numbers.)
• copy_string_array(p) allocates an array of strings, copied from the pointer to a string array
p (a char **).
Low-level interface
The following functions are slightly more efficient than alloc, but also much more difficult to use.
From the standpoint of the allocation functions, blocks are divided according to their size as
zero-sized blocks, small blocks (with size less than or equal to Max_young_wosize), and large blocks
(with size greater than Max_young_wosize). The constant Max_young_wosize is declared in the
include file mlvalues.h. It is guaranteed to be at least 64 (words), so that any block with constant
size less than or equal to 64 can be assumed to be small. For blocks whose size is computed at
run-time, the size must be compared against Max_young_wosize to determine the correct allocation
procedure.
• alloc_small(n, t) returns a fresh small block of size n ≤ Max_young_wosize words, with
tag t. If this block is a structured block (i.e. if t < No_scan_tag), then the fields of the block
(initially containing garbage) must be initialized with legal values (using direct assignment
to the fields of the block) before the next allocation.
• alloc_shr(n, t) returns a fresh block of size n, with tag t. The size of the block can
be greater than Max_young_wosize. (It can also be smaller, but in this case it is more