[llvm-ocaml] Revise OCaml opaque pointer bindings to match rest of API

[alan]

Per the discussion on https://discourse.llvm.org/t/i-accidentally-created-a-naming-inconsistency-in-the-ocaml-api/65715, I renamed the pointer_type_in_context function I previously added. Because this function takes an address space as an argument, I decided to rename it to qualified_pointer_type2, rather than pointer_type2, to match the existing qualified_pointer_type function, which also takes an address space as an argument. Then, I added another function, pointer_type2, which uses the opaque pointer API and does not take an address space as an argument, to correspond with the pointer_type function.

I also changed as to a in the documentation because as is an OCaml keyword and therefore not a valid variable name. (The occurrence of as in the documentation comment was colored like a keyword in my editor, so it stood out to me.)

[alan]

Make doc comment of pointer_type2 refer to getUnqual, not get

[alan]

Also, I chose not to use the word "opaque" in the docs because once typed pointers are phased out, *all* pointers will be opaque pointers.

[alan]

According to https://llvm.org/docs/OpaquePointers.html#version-support, LLVM 16 will not support typed pointers. So, if this patch is not going into an LLVM 15 minor or patch release, could one totally remove the old pointer_type and qualified_pointer_type functions and give their names to pointer_type2 and qualified_pointer_type2? However, that involves rewriting the tests, which use the old functions, and I'm not an expert on what all the tests are supposed to check...

[alan]

I now made https://reviews.llvm.org/D135524, which is an alternative to this patch. For context, see https://discourse.llvm.org/t/i-accidentally-created-a-naming-inconsistency-in-the-ocaml-api/65715. I intend for either one or the other to be merged depending on which my reviewers think is more appropriate.

[alan]

Superseded by https://reviews.llvm.org/rGd226244ae0f5b85d21c9cd23f27f1d7890ea3b4f.

llvm/bindings/ocaml/llvm/llvm.ml

 
 (*--... Operations on pointer, vector, and array types .....................--*)
 
 external subtypes : lltype -> lltype array = "llvm_subtypes"
 external array_type : lltype -> int -> lltype = "llvm_array_type"
 external pointer_type : lltype -> lltype = "llvm_pointer_type"
 external qualified_pointer_type : lltype -> int -> lltype
                                 = "llvm_qualified_pointer_type"
-external pointer_type_in_context : llcontext -> int -> lltype
-                                 = "llvm_pointer_type_in_context"
+external pointer_type2 : llcontext -> lltype = "llvm_pointer_type2"
+external qualified_pointer_type2 : llcontext -> int -> lltype
+                                 = "llvm_qualified_pointer_type2"
 external vector_type : lltype -> int -> lltype = "llvm_vector_type"
 
 external element_type : lltype -> lltype = "LLVMGetElementType"
 external array_length : lltype -> int = "llvm_array_length"
 external address_space : lltype -> int = "llvm_address_space"
 external vector_size : lltype -> int = "llvm_vector_size"
 
 (*--... Operations on other types ..........................................--*)

llvm/bindings/ocaml/llvm/llvm.mli

(** [array_type ty n] returns the array type containing [n] elements of type
     [ty]. See the method [llvm::ArrayType::get]. *)
 val array_type : lltype -> int -> lltype
 
 (** [pointer_type ty] returns the pointer type referencing objects of type
     [ty] in the default address space (0).
     See the method [llvm::PointerType::getUnqual]. *)
 val pointer_type : lltype -> lltype
 
-(** [qualified_pointer_type ty as] returns the pointer type referencing objects
-    of type [ty] in address space [as].
+(** [qualified_pointer_type ty a] returns the pointer type referencing objects
+    of type [ty] in address space [a].
     See the method [llvm::PointerType::get]. *)
 val qualified_pointer_type : lltype -> int -> lltype
 
-(** [pointer_type_in_context context as] returns the opaque pointer type
-    referencing objects in address space [as].
+(** [pointer_type2 context] returns the pointer type in the default
+    address space (0).
     See the method [llvm::PointerType::get]. *)
-val pointer_type_in_context : llcontext -> int -> lltype
+val pointer_type2 : llcontext -> lltype
+
+(** [qualified_pointer_type2 context a] returns the pointer type referencing
+    objects in address space [a].
+    See the method [llvm::PointerType::get]. *)
+val qualified_pointer_type2 : llcontext -> int -> lltype
 
 (** [vector_type ty n] returns the array type containing [n] elements of the
     primitive type [ty]. See the method [llvm::ArrayType::get]. *)
 val vector_type : lltype -> int -> lltype
 
 (** [element_type ty] returns the element type of the pointer, vector, or array
     type [ty]. See the method [llvm::SequentialType::get]. *)
 val element_type : lltype -> lltype

llvm/bindings/ocaml/llvm/llvm_ocaml.c

 }
 
 /* lltype -> int -> lltype */
 LLVMTypeRef llvm_qualified_pointer_type(LLVMTypeRef ElementTy,
                                         value AddressSpace) {
   return LLVMPointerType(ElementTy, Int_val(AddressSpace));
 }
 
+/* llcontext -> lltype */
+LLVMTypeRef llvm_pointer_type2(LLVMContextRef C, value AddressSpace) {
+  return LLVMPointerTypeInContext(C, 0);
+}
+
 /* llcontext -> int -> lltype */
-LLVMTypeRef llvm_pointer_type_in_context(LLVMContextRef C, value AddressSpace) {
+LLVMTypeRef llvm_qualified_pointer_type2(LLVMContextRef C, value AddressSpace) {
   return LLVMPointerTypeInContext(C, Int_val(AddressSpace));
 }
 
 /* lltype -> int -> lltype */
 LLVMTypeRef llvm_vector_type(LLVMTypeRef ElementTy, value Count) {
   return LLVMVectorType(ElementTy, Int_val(Count));
 }
 

llvm/test/Bindings/OCaml/core.ml

 
 let test_contained_types () =
   let ar = struct_type context [| i32_type; i8_type |] in
   insist (i32_type = (Array.get (subtypes ar)) 0);
   insist (i8_type = (Array.get (subtypes ar)) 1)
 
 (*===-- Pointer types  ----------------------------------------------------===*)
 let test_pointer_types () =
-  insist (address_space (pointer_type_in_context context 0) = 0);
-  insist (address_space (pointer_type_in_context context 1) = 1)
+  insist (address_space (pointer_type2 context) = 0);
+  insist (address_space (qualified_pointer_type2 context 0) = 0);
+  insist (address_space (qualified_pointer_type2 context 1) = 1)
 
 (*===-- Conversion --------------------------------------------------------===*)
 
 let test_conversion () =
   insist ("i32" = (string_of_lltype i32_type));
   let c = const_int i32_type 42 in
   insist ("i32 42" = (string_of_llvalue c))