// Describes a computation at the HLO level.
//
-// An HloComputation contains a directed acyclic graph of HLO instructions. The
-// computation has a single root instruction which produces the output of the
-// computation.
+// You can think of an HloComputation like a function. It has some inputs
+// (parameters) and returns exactly one value (the value of its root node). If
+// you want to return multiple values, you can return a tuple.
+//
+// The instructions inside of a computation do not have an explicit total order.
+// Instead, they have a partial order determined by their data and control
+// dependencies.
+//
+// An HloModule contains one "entry computation" -- this is like main() in a C
+// program. Every other computation inside of a module is attached to one or
+// more HloInstructions, as a "nested computation". For example, the kMap
+// instruction has a nested computation and "applies" it to every element of its
+// input, elementwise. (That is, the input [x, y, z] is transformed to [f(x),
+// f(y), f(z)].)
class HloComputation {
public:
// Builder class for HloComputation.
tensorflow::gtl::FlatMap<string, string> canonical_name_map;
};
-// HLO instructions are the IR used by the high-level compiler.
+// HLO instructions are the atomic unit of the high-level compiler's IR.
+//
+// HloInstructions live inside of an HloComputation, which is analogous to a
+// function in other programming languages. Nodes have no total order within
+// their computation. Instead, they have a partial ordering determined by their
+// data and control dependencies.
+//
+// HLO does not have basic blocks or explicit "branch" instructions. Instead,
+// certain HloInstructions -- namely, kWhile, kConditional, and kCall -- encode
+// control flow. For example, the kConditional HLO executes one of two possible
+// computations, depending on the runtime value of a predicate.
+//
+// HLO is pure (mostly). It has no concept of mutable state. Instead, data
+// values are produced by one HLO and flow into consumers across dependency
+// edges.
class HloInstruction {
public:
// A fusion node computes the same value a call to its fusion computation
// Describes a compilation unit at the HLO level.
//
-// A HLO module contains one or more HLO computations. The module contains one
-// "entry" computation which produces the result. The module also includes any
-// embedded computations used by instructions such as "map" and "reduce". All
-// computations are owned by the module.
+// HloModule is the top-level unit in the HLO IR. It corresponds to a whole
+// "program". Running a module, from beginning to end, is the only way to run
+// an XLA program.
+//
+// A module contains one "entry computation"; this HloComputation is like main()
+// in a C program. The result of running the module is the result of running
+// this computation.
+//
+// A module also contains some number of "nested computations". Each nested
+// computation is attached to an HloInstruction within some other computation.
+// The meaning of the nested computation depends on the instruction it's
+// attached to.
class HloModule {
public:
HloModule(const string& name,
projects / platform / upstream / tensorflow.git / commitdiff