package camlid

  1. Overview
  2. Docs

Module Camlid.HelperSource

Function description

Sourceval func : ?ml:string -> ?result:Type.mlc -> ?ignored_result:Type.mlc -> ?call_params:Type.param list -> string -> Type.param list -> Expr.expr

Describe the signature of a C function and generate the stub. Three variants:

  • func ~ml c_name params : the C function has a void result (no result)
  • func ~ml ~result c_name params: the C function has a result with template result, and it is part of the OCaml results
  • func ~ml ~ignored_result c_name params: C function has a result with template result, and it is ignored for the OCaml function

The resulting expression is the OCaml declaration for the external. Since it mentions the Camlid.Expr.id of the C stub function, it is automatically added to the C file during the generation by Camlid.Generate.to_file.

The order of the inputs, outputs (result first), and arguments of the C function all use the order given by params.

  • parameter ml

    name to use for the OCaml function

  • parameter c_name

    is the name of the C function

  • parameter params

    usually parameters of the C function. More generally when using Camlid.Expert, it gives all the variables and their functions used for the generation of the C stub function.

  • parameter call_params

    allows to reorder the list of parameters for the call to the stubbed function (by default params)

Creating parameters from templates

The following functions create fresh variable, the same parameter should not be used multiple times in the description of the same C function. However it could be used in different descriptions

Sourceval input : ?name:string -> Type.mlc -> Type.param

input ~name ty create an input parameter using the typedef template ty. The parameter:

  • appears in the arguments of the ML function
  • is used in the C call
  • is not present in the results.
  • parameter name

    Basename used for the fresh generated variable

  • parameter ty

    Template used for generatiing the parameter.

Sourceval output : ?name:string -> Type.mlc -> Type.param

input ~name ty create an input parameter using the typedef template ty. The parameter:

  • does not appear in the arguments of the ML function
  • is used in the C call
  • is present in the results.
  • parameter name

    Basename used for the fresh generated variable

  • parameter ty

    template used for generatiing the parameter.

Sourceval inout : ?name:string -> Type.mlc -> Type.param

input ~name ty create an input parameter using the typedef template ty. The parameter:

  • does not appear in the arguments of the ML function
  • is used in the C call
  • is present in the results.
  • parameter name

    Basename used for the fresh generated variable

  • parameter ty

    template used for generatiing the parameter.

Sourceval ignored : ?name:string -> Type.mlc -> Type.param

input ~name ty create an input parameter using the typedef template ty. The parameter:

  • does not appear in the arguments of the ML function
  • is used in the C call
  • is not present in the results.
  • parameter name

    Basename used for the fresh generated variable

  • parameter ty

    template used for generatiing the parameter.

Common OCaml values

Sourceval int : Type.mlc

It is int in OCaml, and intptr_t in C. The highest bit is lost when going from C to OCaml

Sourceval size_t : Type.mlc

It is int in OCaml, and size_t in C. The highest bit is lost when going from C to OCaml. Unsigned version of int

Sourceval int_trunc : Type.mlc

It is int in OCaml, and int in C. On 64bit, half of the highest bit are lost (63 bit long in OCaml and 32 bit long in C).

Sourceval double : Type.mlc

It is float in OCaml, and double in C. No loss during conversion.

Sourceval int32 : Type.mlc

It is int32 in OCaml, and int32_t in C. No loss during conversion.

Sourceval int64 : Type.mlc

It is int64 in OCaml, and int64_t in C. No loss during conversion.

Sourceval nativeint : Type.mlc

It is nativeint in OCaml, and intptr_t in C. No loss during conversion.

Sourceval bool : Type.mlc

It is bool in OCaml, and int in C. No loss during conversion if the int is considered as a boolean.

Sourceval ptr_ref : Type.mlc -> Type.mlc

ptr_def ty it change the C value used when calling the C function to a pointer on the given type. It is useful with output. The pointer is valid for the duration og the call. The OCaml type is the same as for ty.

Allocated C structure

In all the following section, owned indicates if the OCaml sides owns the C allocated memory, and so it it should free it want it is not using it anymore. An OCaml value (e.g. a string) is always owned by the OCaml side, the question is if the memory allocated by the stub and given to the C function, or the memory returned by the C function is owned by the OCaml side and should be freed.

Except in the case of bigarrays, or user defined abstract and custom type the allocated memory is freed at the end of the stub

In all this section, init indicates if the stub need to allocate the memory before calling the C function

Sourceval string_nt : ?owned:bool -> unit -> Type.mlc

It is string in OCaml, and char * in C. In both side the conversion stops at the first null character. If there is no null character in the OCaml string it stops at the end.

Sourcetype with_length = {
  1. t : Type.param;
  2. len : Type.param;
}
Sourceval input_string : ?owned:bool -> ?input:bool -> ?output:bool -> ?name:string -> unit -> with_length

Parameter for a "char*" and its length. Given as such to the stubbed function. Converted from/to a string in ocaml.

Sourceval output_string : ?owned:bool -> ?input:bool -> ?output:bool -> ?name:string -> unit -> with_length

Parameter for a "char*" and its length. The address of those variables are given to the stubbed function. Converted from/to a string in ocaml.

Sourceval fixed_length_string : ?init:bool -> ?owned:bool -> ?input:bool -> ?output:bool -> ?len_used_in_call:bool -> ?name:string -> unit -> with_length

Parameter for a "char*" converted (if input) or allocated (if output) with the length given as input. (fixed_length_string ()).len is an input parameter. Converted from/to a string in ocaml.

Sourceval input_array : ?owned:bool -> ?output:bool -> ?input:bool -> ?name:string -> Type.mlc -> with_length

input_array mlc Parameter for an array of mlc and its length. Given as such to the stubbed function. Converted from/to an array of mlc in OCaml.

Sourceval output_array : ?owned:bool -> ?output:bool -> ?input:bool -> ?name:string -> Type.mlc -> with_length

output_array mlc Parameter for an array of mlc and its length. The address of those variables are given to the stubbed function. Converted from/to an array of mlc in OCaml.

Sourceval fixed_length_array : ?init:bool -> ?owned:bool -> ?input:bool -> ?output:bool -> ?len_used_in_call:bool -> ?name:string -> Type.mlc -> with_length

fixed_length_array mlc Parameter for an array of mlc converted (if input) or allocated (if output) with the length given as input. (fixed_length_array ()).len is an input parameter. Converted from/to an array of mlc in OCaml.

Sourceval abstract : ?initialize:string -> ?get:string -> ?set:string -> ?internal:string -> ml:string -> c:string -> unit -> Type.mlc
Sourceval custom : ?initialize:string -> ?finalize:string -> ?hash:string -> ?compare:string -> ?get:string -> ?set:string -> ?internal:string -> ml:string -> c:string -> unit -> Type.mlc
Sourceval custom_ptr : ?initialize:string -> ?finalize:string -> ?hash:string -> ?compare:string -> ?malloc:bool -> ml:string -> c:string -> unit -> Type.mlc
Sourceval algdata : string -> (string * (string * Type.mlc) list) list -> Type.mlc
Sourceval string_as_FILE_ptr : Type.mlc
Sourceval input_value : string -> Type.param
Sourceval output_value : string -> Type.param
Sourceval module_ : string -> Expr.expr list -> Expr.expr
Sourceval ml_alias : string -> Type.mlc -> Expr.expr
Sourceval copy : Type.mlc -> ?vars:(dst:Expr.Var.t -> src:Expr.Var.t -> Expr.Var.t list) -> ?exprs:(dst:Expr.Var.t -> src:Expr.Var.t -> Expr.expr list) -> string -> Type.mlc
Sourceval ret_option_if : Type.mlc -> Type.param * Type.mlc
Sourceval get_expression : name:string -> Type.mlc -> string -> Expr.expr
Sourceval map_param_in_call : ?name:string -> ty:string -> Type.param -> (('a -> Expr.expr -> 'b) -> Expr.expr -> 'c, 'a, 'b, 'd, 'd, 'c) format6 -> Type.param
Sourceval do_nothing : string -> Type.param list -> Expr.expr
Sourceval convert : ?c_to_mlc:string -> ?mlc_to_c:string -> ?using:Expr.Var.t list -> mlc:Type.mlc -> c:Type.c -> unit -> Type.mlc
Sourceval on_stack : ?init_expr:string -> ?initialize:string -> ?clear:string -> string -> Type.c

Define a C type that is allocated on the stack. It is initialized and cleared with the given functions.

  • parameter init_expr

    is the initialization expression used