Module Std.Value

Universal Values.

This module creates an extensible variant type, that resembles extensible variant types, introduced in 4.02, but even more safe and more extensible, and, what really matters, serializable. Basically you should think of Value.t as a union type, aka sum type, that can be extended in any place, including your plugin code. Where extending is adding new constructor. To add new constructor, you need to register it, e.g.,

  let function_signature = Value.Tag.register (module String)
      ~name:"function_signature"
      ~uuid:"2175c28c-08ca-4052-8385-3a01e1c6ab6f"

This is merely equivalent to adding a branch

  | Function_signature of string

to existing union type. The main difference is that the name shouldn't be unique (in fact name doesn't bear any semantic meaning, it basically for pretty-printing). On the other hand the uuid parameter must be unique across the universe, space and time. To get the UUID with such properties, you can use uuidgen program that is usually available on Linux and Mac OS.

name and uuid must be strings, known at compile time, in other words it must be string literal, not just an arbitrary string, created dynamically. This is made intentionally, in order to prevent the abuse of the system.

The (module String) syntax creates a value from the module String, (so called first-class module). The module should implement Value.S signature, that requires pretty-printing, comparison function and serialization.

  module type S = sig
    type t with bin_io, compare, sexp

    val pp : Format.formatter -> t -> unit
  end

The good news is that, most of the types in Core and Bap do conform with the requirements. Usually, one can implement the requirements very easily by using type-driven syntax extensions (although, you still need to implement pretty-printing function yourself):

  module Loc = struct
    type t = string * int * int
    with bin_io, compare, sexp

    let pp ppf (file,line,col) =
      Format.fprintf ppf "%s:%d:%d" file line col
  end

  let loc = Value.Tag.register (module Loc)
      ~name:"loc"
      ~uuid:"400e190e-ce21-488d-87b1-c101709621a8"

The returned value, is a tag that can be used to constructed values of that branch, and to deconstruct (extract) them. You may think of it as a cipher key, that is used to package data into the value container, and later to unpack it:

  # let main_pos = Value.create loc ("test.c", 20, 2);;
  val main_pos : value = test.c:20:2

You may see, that OCaml pretty-prints the value. That's neat! Also, you may see, that the returned expression has type value. That means that it can be used uniformly with other values, for example, you can put them in one container, e.g.,

  # let main_t = Value.create function_signature
        "void main(int argc, const char *argv[])";;
  val main_t : value = void main(int argc, const char *argv[])

  # let main = [main_pos; main_t];;
  val main : value list = [
      test.c:20:2;
      void main(int argc, const char *argv[])
    ]

To extract value you can use Value.get function:

  # Value.get loc main_pos;;
  - : Loc.t option = Some ("test.c", 20, 2)

This will require an extra allocation of an option container, and in a performance critical context it may be unacceptable. For this special case you can use a more efficient:

if Value.is loc then Value.get_exn loc main_pos

.

Underneath the hood, the values of type value is just a pair of an original value and runtime type information.

The comparison of two values of type value is actually a multi-method, as it has the following behavior:

1. If both values has the same type, then use compare function, that was provided for this type. 2. If values are of different types, that are known to the type system, then compare them using RTTI, and ignore the value. 3. If at least one of the values is of the unknown type, (i.e., type wasn't registered in the type system), then use polymorphic compare on a tuple of UUID and binary representation of the values.

The rules above guarantee, that values with different RTTI id are never equal. It also guarantees that the ordering will be preserved between different builds of a program, and even between different versions of the compiler.

Thread safety

The only thread unsafe function is register, that should be called in the module initialization time. In general programs modules are initialized in a single thread, so this shouldn't be an issue. The implementation by itself doesn't call register.

Or_error.errorf "type %a is not valid for %a"
    Type.str ty Exp.str exp