runtime/array.c: rename make-array functions

[gasche]

This PR introduces new, more consistent names for the C functions in the OCaml runtime that create arrays.

Current situation

The implementation of most array primitives has a fairly regular naming structure. Consider get for example, we have:

(* Array.get *)
external get : 'a array -> int -> 'a = "%array_safe_get"

(* Array.Float.get *)
external get : floatarray -> int -> float = "%floatarray_safe_get"

and on the C side:

/* [ 'a array -> int -> 'a ] */
CAMLprim value caml_array_get(value array, value index)

/* [ floatarray -> int -> float ] */
CAMLprim value caml_floatarray_get(value array, value index)

/* [ 'a array -> int -> 'a ] where 'a != float */
CAMLprim value caml_array_get_addr(value array, value index)

On the other hand, the naming structure of array creation functions is much less regular due to historical baggage. At the OCaml level, we have the following functions to create arrays:

external make : int -> 'a -> 'a array
external create_float: int -> float array

but on the C side we have the following:

/* [ int -> floatarray ] */
CAMLprim value caml_floatarray_create(value len)

/* [ int -> 'a -> 'a array ] */
CAMLprim value caml_make_vect(value len, value init)

/* [ int -> float array ] */
CAMLprim value caml_make_float_vect(value len)

/* This primitive is used internally by the compiler to compile
   explicit array expressions.
   For float arrays when FLAT_FLOAT_ARRAY is true, it takes an array of
   boxed floats and returns the corresponding flat-allocated [float array].
   In all other cases, it just returns its argument unchanged.
*/
CAMLprim value caml_make_array(value init)

There is no obvious naming convention here, in particular make is used to mean three different things:

• create a float array with uninitialized values
• make an 'a array with an initial value
• convert a boxed array into an 'a array

Why change?

Improving this situation is a preliminary step towards uniform_array primitives in the runtime -- see ocaml/RFCs#37 . (One should be able to review new primitives without having to get confused about names at the same time.)

Proposition

I propose to keep the existing names for backward-compatibility reasons (removing primitives is a pain), but also to introduce more regular names to use in the future and (after a bootstrap) in the compiler codebase.

CAMLprim caml_array_make(value len, value init)
/* better name for [caml_make_vect] --
   can be later specialized in [caml_floatarray_make]
   and [caml_uniform_array_make]. */

CAMLprim caml_array_create_float(value len)
/* better name for [caml_make_float_vect] --
   matches the [caml_array_<foo>] naming convention
   for the C counterpart of [Array.foo]. */

CAMLprim caml_array_of_uniform_array
/* new name for [caml_make_array], more explicit
   and avoids confusion with [caml_array_make]. */

[OlivierNicole]

This looks good to me.

[OlivierNicole]

Is this good to merge once there is a Changes entry?

(I guess before merging, the maintainer doing it should also verify the bytecode blobs of the bootstrap commits?)

[gasche]

These PRs usually generate a fair amount of bike-shedding. I don't know if nobody cares or if it slipped by un-noticed because everyone was busy. Let me send an email to ensure that people with opinions had the opportunity to give some of them.

[kayceesrk]

CAMLprim caml_array_make(value len, value init)
CAMLprim caml_array_create_float(value len)

Do we need the distinction between create and make? I'm not a native English speaker, but the distinction between make and create isn't clear to me. Can we settle on just one of the terms? I get tripped up between create and make and I have to look it up often.

[nojb]

CAMLprim caml_array_make(value len, value init)
CAMLprim caml_array_create_float(value len)

Do we need the distinction between create and make? I'm not a native English speaker, but the distinction between make and create isn't clear to me. Can we settle on just one of the terms? I get tripped up between create and make and I have to look it up often.

Historically, make was used for "create with an init value", while create meant "create with uninitialized contents" (see eg Float.Array.{make,create}.

[kayceesrk]

Thanks for the clarification @nojb.

[gasche]

@hhugo I see that js_of_ocaml would be affected by the part of this PR that uses the new primitives in the code produced by the compiler -- of course. Does it make your life easier if this part of the change is delayed to a future release of OCaml?

[hhugo]

@hhugo I see that js_of_ocaml would be affected by the part of this PR that uses the new primitives in the code produced by the compiler -- of course. Does it make your life easier if this part of the change is delayed to a future release of OCaml?

Any release after 5.2 would be fine.

[gasche]

To be clear, this PR -- if merged -- would go to trunk, to be released in future 5.3. I'm not sure if you mean that it does not matter when the change to compiler-produced output happens, or if you mean that it is better if the change happens at least one release after the new names are introduced.

[hhugo]

To be clear, this PR -- if merged -- would go to trunk, to be released in future 5.3. I'm not sure if you mean that it does not matter when the change to compiler-produced output happens, or if you mean that it is better if the change happens at least one release after the new names are introduced.

I say after 5.2 is better because I've already released a version of jsoo compatible with 5.2 and I'd prefer to not have to do another one. But in general, I don't really care when such change happen.

[gasche]

I just pushed a rebase that adds a Changes entry and removes the bootstrap commit: we are only extending the runtime with new functions, which are mentioned in the code generated by the new compiler, it looks like this does not require a bootstrap.