runtime/array.c: rename make-array functions by gasche · Pull Request #13003 · ocaml/ocaml

gasche · 2024-03-03T22:52:31Z

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 · 2024-04-09T15:01:40Z

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 · 2024-04-09T16:44:19Z

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 · 2024-04-10T06:00:52Z

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 · 2024-04-10T06:28:18Z

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 · 2024-04-10T09:08:03Z

Thanks for the clarification @nojb.

gasche · 2024-04-10T18:55:45Z

@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 · 2024-04-10T19:46:52Z

@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 · 2024-04-10T20:07:02Z

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 · 2024-04-10T20:22:20Z

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 · 2024-04-14T20:14:45Z

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.

gasche force-pushed the rename-array-make-runtime-functions branch from d72a265 to ed48566 Compare March 3, 2024 23:11

OlivierNicole approved these changes Mar 12, 2024

View reviewed changes

gasche force-pushed the rename-array-make-runtime-functions branch from ed48566 to e0bb2ac Compare April 3, 2024 19:14

hhugo mentioned this pull request Apr 10, 2024

Support for OCaml trunk ocsigen/js_of_ocaml#1487

Closed

11 tasks

gasche added 5 commits April 14, 2024 21:33

runtime/array.c: less confusing array-creation primitive names

f01aa71

caml_make_vect => caml_array_make

d9b6757

caml_make_float_vect => caml_array_create_float

2f4990d

caml_make_array => caml_array_of_uniform_array

ad1acdb

Changes

4bb1965

gasche force-pushed the rename-array-make-runtime-functions branch from e0bb2ac to 4bb1965 Compare April 14, 2024 20:13

gasche merged commit d0ac496 into ocaml:trunk Apr 17, 2024

kit-ty-kate mentioned this pull request May 16, 2024

Add support for OCaml 5.3 ygrek/ocaml-extlib#73

Merged

NickBarnes mentioned this pull request Feb 3, 2026

Backport #13003 (runtime/array.c: rename make-array functions) from upstream oxcaml/oxcaml#5339

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

runtime/array.c: rename make-array functions#13003

runtime/array.c: rename make-array functions#13003
gasche merged 5 commits intoocaml:trunkfrom
gasche:rename-array-make-runtime-functions

gasche commented Mar 3, 2024

Uh oh!

OlivierNicole left a comment

Uh oh!

OlivierNicole commented Apr 9, 2024

Uh oh!

gasche commented Apr 9, 2024

Uh oh!

kayceesrk commented Apr 10, 2024

Uh oh!

nojb commented Apr 10, 2024

Uh oh!

kayceesrk commented Apr 10, 2024

Uh oh!

gasche commented Apr 10, 2024

Uh oh!

hhugo commented Apr 10, 2024

Uh oh!

gasche commented Apr 10, 2024

Uh oh!

hhugo commented Apr 10, 2024

Uh oh!

gasche commented Apr 14, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

gasche commented Mar 3, 2024

Current situation

Why change?

Proposition

Uh oh!

OlivierNicole left a comment

Choose a reason for hiding this comment

Uh oh!

OlivierNicole commented Apr 9, 2024

Uh oh!

gasche commented Apr 9, 2024

Uh oh!

kayceesrk commented Apr 10, 2024

Uh oh!

nojb commented Apr 10, 2024

Uh oh!

kayceesrk commented Apr 10, 2024

Uh oh!

gasche commented Apr 10, 2024

Uh oh!

hhugo commented Apr 10, 2024

Uh oh!

gasche commented Apr 10, 2024

Uh oh!

hhugo commented Apr 10, 2024

Uh oh!

gasche commented Apr 14, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants