Legend:
Library
Module
Module type
Parameter
Class
Class type
Basic block.
Logically block consists of a set of phi nodes, a sequence of definitions and a sequence of out-coming edges, aka jumps. A colloquial term for this three entities is a block element.
The order of Phi-nodes can be specified in any order, as they execute simultaneously . Definitions are stored in the order of execution. Jumps are specified in the order in which they should be taken, i.e., jmp_n is taken only after jmp_n-1 and if and only if the latter was not taken. For example, if block ends with N jumps, where each n-th jump have destination named t_n and condition c_n then it would have the semantics as per the following OCaml program:
if c_1 then jump t_1 else
if c_2 then jump t_2 else
if c_N then jump t_N else
stop
from_insn ?addr insn creates an IR representation of a single machine instruction insn.
Uses the Term.slot to get the IR representation of an instruction, trying to keep the number of basic blocks minimal (by coalescing adjacent data operations).
If addr is specified then the term identifier of the first block will be specific to that address and the address attribute will be set to the passed value.
from_insns block translates a basic block of instructions into IR.
Takes a list of instructions in the execution order and translates them into a list of IR blks that are properly connected. The instructions shall belong to a single basic block.
The first element of the result is the entry block. If addr is set then it will have the term identifier equal to Term.for_addr addr and the address attribute will be set to addr.
The fall parameter designates the fallthrough destination of the basic block. The destination could be either interprocedural (`Inter) or intraprocedural (`Intra). In the latter case it will be reified into a jump of the call kind. If the last instruction (the basic block terminator) is a barrier Insn.(is barrier) is [true], then the fall destination is ignored, even if set.
split_while blk ~f splits blk into two block: the first block holds all definitions for which f p is true and has the same tid as blk. The second block is freshly created and holds the rest definitions (if any). All successors of the blk become successors of the second block, which becomes the successor of the first block.
Note: if f def is true for all blocks, then the second block will not contain any definitions, i.e., the result would be the same as of split_bot function.
split_top blk returns two blocks, where first block shares the same tid as blk and has all $\Phi$-nodes of blk, but has only one destination, namely the second block. Second block has new tidentity, but inherits all definitions and jumps from the blk.
split_top blk returns two blocks, where first block shares the same tid as blk, has all $\Phi$-nodes and definitions from blk, but has only one destination, namely the second block. Second block has new tidentity, all jumps from the blk.
elts ~rev blk return all elements of the blk. if rev is false or left unspecified, then elements are returned in the following order: $\Phi$-nodes, defs (in normal order), jmps in the order in which they will be taken. If rev is true, the order will be the following: all jumps in the opposite order, then definitions in the opposite order, and finally $\Phi$-nodes.
val map_exp : ?skip:[ `phi | `def| `jmp ] list->t->f:(exp->exp)->t
map_exp b ~f applies function f for each expression in block b. By default function f will be applied to all values of type exp, including right hand sides of phi-nodes, definitions, jump conditions and targets. If skip parameter is specified, then terms of corresponding kind will be skipped, i.e., function f will not be applied to them.
map_elt ?phi ?def ?jmp blk applies provided functions to the terms of corresponding classes. All functions default to the identity function.
val substitute : ?skip:[ `phi | `def| `jmp ] list->t->exp->exp->t
substitute ?skip blk x y substitutes each occurrence of expression x with expression y in block blk. The substitution is performed deeply. If skip parameter is specified, then terms of corresponding kind will be left untouched.
val map_lhs : ?skip:[ `phi | `def ] list->t->f:(var->var)->t
map_lhs blk ~f applies f to every left hand side variable in def and phi subterms of blk. If skip parameter is specified, then terms of corresponding kind will be left untouched. E.g., map_lhs ~skip:[`phi] ~f:(substitute vars) will perform a substitution only on definitions (and will ignore phi-nodes)
free_vars blk returns a set of variables that occurs free in block blk. A variable is free, if it occurs unbound in the expression and there is no preceding definition of this variable in a block blk.
uses_var blk x true if variable x is in free_vars blk. If you need to call this function on several variables it is better to compute free_vars explicitly and use Set.mem function.
flatten blk translates blk into the flattened form. In the flattened form, all operations are applied to variables, constants, or unknowns, i.e., the operands could not be compound expressions. E.g.,
This function only needs implementation if t exposed to be a polymorphic variant. Despite what the type reads, this does *not* produce a function after reading; instead it takes the constructor tag (int) before reading and reads the rest of the variant t afterwards.
str () t is formatted output function that matches "%a" conversion format specifier in functions, that prints to string, e.g., sprintf, failwithf, errorf and, surprisingly all Lwt printing function, including Lwt_io.printf and logging (or any other function with type ('a,unit,string,...) formatN`. Example:
Or_error.errorf "type %a is not valid for %a"
Type.str ty Exp.str exp
ascending is identical to compare. descending x y = ascending y x. These are intended to be mnemonic when used like List.sort ~compare:ascending and List.sort
~cmp:descending, since they cause the list to be sorted in ascending or descending order, respectively.
type info = string * [ `Ver of string ] * string option
name,Ver v,desc information attached to a particular reader or writer.
val version : string
Data representation version. After any change in data representation the version should be increased.
Serializers that are derived from a data representation must have the same version as a version of the data structure, from which it is derived. This kind of serializers can only read and write data of the same version.
Other serializers can actually read and write data independent on its representation version. A serializer, that can't store data of current version simply shouldn't be added to a set of serializers.
It is assumed, that if a reader and a writer has the same name and version, then whatever was written by the writer should be readable by the reader. The round-trip equality is not required, thus it is acceptable if some information is lost.
It is also possible, that a reader and a writer that has the same name are compatible. In that case it is recommended to use semantic versioning.
val size_in_bytes : ?ver:string ->?fmt:string ->t-> int
size_in_bytes ?ver ?fmt datum returns the amount of bytes that is needed to represent datum in the given format and version
default_reader returns information about default reader
val set_default_reader : ?ver:string ->string -> unit
set_default_reader ?ver name sets new default reader. If version is not specified then the latest available version is used. Raises an exception if a reader with a given name doesn't exist.
val with_reader : ?ver:string ->string ->(unit ->'a)->'a
with_reader ?ver name operation temporary sets a default reader to a reader with a specified name and version. The default reader is restored after operation is finished.
default_writer returns information about the default writer
val set_default_writer : ?ver:string ->string -> unit
set_default_writer ?ver name sets new default writer. If version is not specified then the latest available version is used. Raises an exception if a writer with a given name doesn't exist.
val with_writer : ?ver:string ->string ->(unit ->'a)->'a
with_writer ?ver name operation temporary sets a default writer to a writer with a specified name and version. The default writer is restored after operation is finished.
default_writer optionally returns an information about default printer
val set_default_printer : ?ver:string ->string -> unit
set_default_printer ?ver name sets new default printer. If version is not specified then the latest available version is used. Raises an exception if a printer with a given name doesn't exist.
val with_printer : ?ver:string ->string ->(unit ->'a)->'a
with_printer ?ver name operation temporary sets a default printer to a printer with a specified name and version. The default printer is restored after operation is finished.