jon.recoil.org

Module Ocaml_typing.Shape

Shapes are an abstract representation of modules' implementations which allow the tracking of definitions through functor applications and other module-level operations.

The Shape of a compilation unit is elaborated during typing, partially reduced (without loading external shapes) and written to the cmt file.

External tools can retrieve the definition of any value (or type, or module, etc) by following this procedure:

See:

module Uid : sig ... end

A Uid.t is associated to every declaration in signatures and implementations. They uniquely identify bindings in the program. When associated with these bindings' locations they are useful to external tools when trying to jump to an identifier's declaration or definition. They are stored to that effect in the uid_to_decl table of cmt files.

module DeBruijn_index : sig ... end

We use de Bruijn indices for some binders in Shape.t below to increase sharing. That is, de Bruijn indices ensure that alpha-equivalent terms are actually equal. This reduces redundancy when we emit shape information into the debug information in later stages of the compiler (see dwarf_type.ml), since equal shapes produce the same debug information.

module Sig_component_kind : sig ... end
module Item : sig ... end

Shape's items are elements of a structure or, in the case of constructors and labels, elements of a record or variants definition seen as a structure. These structures model module components and nested types' constructors and labels.

module Predef : sig ... end
type t = private {
  1. hash : int;
  2. uid : Ocaml_typing.Shape.Uid.t option;
  3. desc : Ocaml_typing.Shape.desc;
  4. approximated : bool;
}
and desc =
  1. | Var of Ocaml_typing.Shape.var
  2. | Abs of Ocaml_typing.Shape.var * Ocaml_typing.Shape.t
  3. | App of Ocaml_typing.Shape.t * Ocaml_typing.Shape.t
  4. | Struct of Ocaml_typing.Shape.t Ocaml_typing.Shape.Item.Map.t
  5. | Alias of Ocaml_typing.Shape.t
  6. | Leaf
  7. | Proj of Ocaml_typing.Shape.t * Ocaml_typing.Shape.Item.t
  8. | Comp_unit of string
  9. | Error of string
  10. | Constr of Ocaml_typing.Ident.t * Ocaml_typing.Shape.t list
  11. | Tuple of Ocaml_typing.Shape.t list
  12. | Unboxed_tuple of Ocaml_typing.Shape.t list
  13. | Predef of Ocaml_typing.Shape.Predef.t * Ocaml_typing.Shape.t list
  14. | Arrow
  15. | Poly_variant of Ocaml_typing.Shape.t Ocaml_typing.Shape.poly_variant_constructors
  16. | Mu of Ocaml_typing.Shape.t
    (*

    Mu t represents a binder for a recursive type with body t. Its variables are Rec_var n below, where n is a DeBruijn-index to maximize sharing between alpha-equivalent shapes.

    *)
  17. | Rec_var of Ocaml_typing.Shape.DeBruijn_index.t
  18. | Variant of (Ocaml_typing.Shape.t * Layout.t) Ocaml_typing.Shape.complex_constructors
  19. | Variant_unboxed of {
    1. name : string;
    2. variant_uid : Ocaml_typing.Shape.Uid.t option;
    3. arg_name : string option;
      (*

      if this is None, we are looking at a singleton tuple; otherwise, it is a singleton record.

      *)
    4. arg_uid : Ocaml_typing.Shape.Uid.t option;
    5. arg_shape : Ocaml_typing.Shape.t;
    6. arg_layout : Layout.t;
    }
    (*

    An unboxed variant corresponds to the @@unboxed annotation. It must have a single, complex constructor.

    *)
  20. | Record of {
    1. fields : (string * Ocaml_typing.Shape.Uid.t option * Ocaml_typing.Shape.t * Layout.t) list;
    2. kind : Ocaml_typing.Shape.record_kind;
    }
  21. | Mutrec of Ocaml_typing.Shape.t Ocaml_typing.Ident.Map.t
    (*

    Mutrec m represents a map of (potentially mutually-recursive) declarations. Declarations with type variables are represented as abstractions inside. To project out a declaration, Proj_decl can be used.

    *)
  22. | Proj_decl of Ocaml_typing.Shape.t * Ocaml_typing.Ident.t

For DWARF type emission to work as expected, we store the layouts in the declaration alongside the shapes in those cases where the layout "expands" again such as variant constructors, which themselves are values but point to blocks in memory. Here, layouts are stored for the individual fields.

and 'a poly_variant_constructors = 'a Ocaml_typing.Shape.poly_variant_constructor list
and 'a poly_variant_constructor = {
  1. pv_constr_name : string;
  2. pv_constr_args : 'a list;
}
and record_kind =
  1. | Record_unboxed
    (*

    Record_unboxed is the case for single-field records declared with @@unboxed, whose runtime representation is simply its contents without any indirection.

    *)
  2. | Record_unboxed_product
    (*

    Record_unboxed_product is the truly unboxed record that corresponds to #{ ... }.

    *)
  3. | Record_boxed
  4. | Record_mixed of Ocaml_typing.Shape.mixed_product_shape
  5. | Record_floats
    (*

    Basically the same as Record_mixed, but we don't reorder the fields.

    *)
and 'a complex_constructors = 'a Ocaml_typing.Shape.complex_constructor list
and 'a complex_constructor = {
  1. name : string;
  2. constr_uid : Ocaml_typing.Shape.Uid.t option;
  3. kind : Ocaml_typing.Shape.constructor_representation;
  4. args : 'a Ocaml_typing.Shape.complex_constructor_argument list;
}
and 'a complex_constructor_argument = {
  1. field_name : string option;
  2. field_uid : Ocaml_typing.Shape.Uid.t option;
  3. field_value : 'a;
}
and constructor_representation = Ocaml_typing.Shape.mixed_product_shape
and mixed_product_shape = Layout.t array
val strip_head_aliases : Ocaml_typing.Shape.t -> Ocaml_typing.Shape.t
val equal_complex_constructor : ('a -> 'a -> bool) -> 'a Ocaml_typing.Shape.complex_constructor -> 'a Ocaml_typing.Shape.complex_constructor -> bool
val for_unnamed_functor_param : Ocaml_typing.Shape.var
val error : ?uid:Ocaml_typing.Shape.Uid.t -> string -> Ocaml_typing.Shape.t
val comp_unit : ?uid:Ocaml_typing.Shape.Uid.t -> string -> Ocaml_typing.Shape.t
val variant_unboxed : ?uid:Ocaml_typing.Shape.Uid.t -> variant_uid:Ocaml_typing.Shape.Uid.t option -> arg_uid:Ocaml_typing.Shape.Uid.t option -> string -> string option -> Ocaml_typing.Shape.t -> Layout.t -> Ocaml_typing.Shape.t
val set_approximated : approximated:bool -> Ocaml_typing.Shape.t -> Ocaml_typing.Shape.t
val for_persistent_unit : string -> Ocaml_typing.Shape.t
val leaf_for_unpack : Ocaml_typing.Shape.t
val poly_variant_constructors_map : ('a -> 'b) -> 'a Ocaml_typing.Shape.poly_variant_constructors -> 'b Ocaml_typing.Shape.poly_variant_constructors
val complex_constructor_map : ('a -> 'b) -> 'a Ocaml_typing.Shape.complex_constructor -> 'b Ocaml_typing.Shape.complex_constructor
val complex_constructors_map : ('a -> 'b) -> 'a Ocaml_typing.Shape.complex_constructors -> 'b Ocaml_typing.Shape.complex_constructors
module Map : sig ... end
val dummy_mod : Ocaml_typing.Shape.t

This function returns the shape corresponding to a given path. It requires a callback to find shapes in the environment. It is generally more useful to rely directly on the Env.shape_of_path function to get the shape associated with a given path.

module DeBruijn_env : sig ... end

DeBruijn Environment for working with the recursive binders.