package bap-std

  1. Overview
  2. Docs
On This Page
  1. Thread safety
package bap-std
Legend:
Library
Module
Module type
Parameter
Class
Class type

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.

type t = value

a universal value

include Core_kernel.Bin_prot.Binable.S with type t := t
include Ppx_sexp_conv_lib.Sexpable.S with type t := t
type 'a tag

Tag constructor of type 'a

module type S = sig ... end

A required interface for the type to be lifted to value.

type void

uninhabited type

type literal = (void, void, void) Core_kernel.format

literal string. Don't look at the right hand side of a type equation, this is just a way to say that a string should be a literal not a value. Compiler will automatically coerce your string literals to this type.

type typeid

persistent type identifier

val bin_shape_typeid : Core_kernel.Bin_prot.Shape.t
val bin_size_typeid : typeid Core_kernel.Bin_prot.Size.sizer
val bin_write_typeid : typeid Core_kernel.Bin_prot.Write.writer
val bin_writer_typeid : typeid Core_kernel.Bin_prot.Type_class.writer
val bin_read_typeid : typeid Core_kernel.Bin_prot.Read.reader
val __bin_read_typeid__ : (int -> typeid) Core_kernel.Bin_prot.Read.reader
val bin_reader_typeid : typeid Core_kernel.Bin_prot.Type_class.reader
val bin_typeid : typeid Core_kernel.Bin_prot.Type_class.t
val compare_typeid : typeid -> typeid -> int
val sexp_of_typeid : typeid -> Ppx_sexp_conv_lib.Sexp.t
val typeid_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> typeid
val create : 'a tag -> 'a -> t

create cons x creates a value using constructor cons and argument x

val is : 'a tag -> t -> bool

is cons v true if value v was constructed with constructor cons, i.e., it is true only when is_cons t (create t x)

val get : 'a tag -> t -> 'a option

get cons extracts a value associated with a constructor cons (Essentially, performs a pattern match on the specified variant branch)

val get_exn : 'a tag -> t -> 'a

get_exn t v extracts value created with t from the variant. Raises unspecified exception if variant v wasn't created with t.

val tagname : t -> string

tagname value returns a constructor name of the value

val typeid : t -> typeid

typeid value returns a type identifier of the value

module Tag : sig ... end

Variants of values.

module Match : sig ... end

Runtime parallel match.

module Typeid : Core_kernel.Identifiable with type t = typeid

Persistent type identifiers.

Although values of type value implements regular interface it is recommended to used dict data structure instead of those, that are provided by Regular interface.x

include Regular.Std.Regular.S with type t := t
val bin_size_t : t Bin_prot.Size.sizer
val bin_write_t : t Bin_prot.Write.writer
val bin_read_t : t Bin_prot.Read.reader
val __bin_read_t__ : (int -> t) Bin_prot.Read.reader
val bin_shape_t : Bin_prot.Shape.t
val bin_writer_t : t Bin_prot.Type_class.writer
val bin_reader_t : t Bin_prot.Type_class.reader
val bin_t : t Bin_prot.Type_class.t
val t_of_sexp : Sexplib0__.Sexp.t -> t
val sexp_of_t : t -> Sexplib0__.Sexp.t
val to_string : t -> string
val str : unit -> t -> string
val pps : unit -> t -> string
val ppo : Core_kernel.Out_channel.t -> t -> unit
val pp_seq : Stdlib.Format.formatter -> t Core_kernel.Sequence.t -> unit
val pp : Base__.Formatter.t -> t -> unit
val (>=) : t -> t -> bool
val (<=) : t -> t -> bool
val (=) : t -> t -> bool
val (>) : t -> t -> bool
val (<) : t -> t -> bool
val (<>) : t -> t -> bool
val equal : t -> t -> bool
val compare : t -> t -> int
val min : t -> t -> t
val max : t -> t -> t
val ascending : t -> t -> int
val descending : t -> t -> int
val between : t -> low:t -> high:t -> bool
val clamp_exn : t -> min:t -> max:t -> t
val clamp : t -> min:t -> max:t -> t Base__.Or_error.t
type comparator_witness
val validate_lbound : min:t Base__.Maybe_bound.t -> t Base__.Validate.check
val validate_ubound : max:t Base__.Maybe_bound.t -> t Base__.Validate.check
val validate_bound : min:t Base__.Maybe_bound.t -> max:t Base__.Maybe_bound.t -> t Base__.Validate.check
module Replace_polymorphic_compare : sig ... end
val comparator : (t, comparator_witness) Core_kernel__Comparator.comparator
module Map : sig ... end
module Set : sig ... end
val hash_fold_t : Ppx_hash_lib.Std.Hash.state -> t -> Ppx_hash_lib.Std.Hash.state
val hash : t -> Ppx_hash_lib.Std.Hash.hash_value
val hashable : t Core_kernel__.Hashtbl.Hashable.t
module Table : sig ... end
module Hash_set : sig ... end
module Hash_queue : sig ... end
type info = string * [ `Ver of string ] * string option
val version : string
val size_in_bytes : ?ver:string -> ?fmt:string -> t -> int
val of_bytes : ?ver:string -> ?fmt:string -> Regular.Std.bytes -> t
val to_bytes : ?ver:string -> ?fmt:string -> t -> Regular.Std.bytes
val blit_to_bytes : ?ver:string -> ?fmt:string -> Regular.Std.bytes -> t -> int -> unit
val of_bigstring : ?ver:string -> ?fmt:string -> Core_kernel.bigstring -> t
val to_bigstring : ?ver:string -> ?fmt:string -> t -> Core_kernel.bigstring
val blit_to_bigstring : ?ver:string -> ?fmt:string -> Core_kernel.bigstring -> t -> int -> unit
module Io : sig ... end
module Cache : sig ... end
val add_reader : ?desc:string -> ver:string -> string -> t Regular.Std.reader -> unit
val add_writer : ?desc:string -> ver:string -> string -> t Regular.Std.writer -> unit
val available_readers : unit -> info list
val default_reader : unit -> info
val set_default_reader : ?ver:string -> string -> unit
val with_reader : ?ver:string -> string -> (unit -> 'a) -> 'a
val available_writers : unit -> info list
val default_writer : unit -> info
val set_default_writer : ?ver:string -> string -> unit
val with_writer : ?ver:string -> string -> (unit -> 'a) -> 'a
val default_printer : unit -> info option
val set_default_printer : ?ver:string -> string -> unit
val with_printer : ?ver:string -> string -> (unit -> 'a) -> 'a
val find_reader : ?ver:string -> string -> t Regular.Std.reader option
val find_writer : ?ver:string -> string -> t Regular.Std.writer option
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct