Documentation
¶
Overview ¶
Package kernel runs notebooks.
A Kernel owns a work directory holding a Go module: the generated program of the notebook, compiled into a worker process it drives (see package runtime). Each Run takes the notebook's current code cells and does the least work that brings every result up to date:
- A cell's key is a hash of its source, of the notebook's imports and of the keys of the cells it reads. A cell whose key has not changed keeps its result and is not run.
- When the program changes the worker is rebuilt and restarted. The values of unchanged cells are handed to the new worker instead of being computed again. A value that cannot be encoded (a func, a channel, unexported state) is volatile: its cell runs again, but only when a cell that reads it has to run.
- A cell that fails stops the cells that read it, which report why.
Results and values are also kept on disk in the work directory, so a new Kernel on the same directory picks up where the last one stopped.
This assumes a cell computes the same values from the same inputs, which a cell reading the clock or an unseeded generator does not; such a cell should be run explicitly (RunCell).
Index ¶
Constants ¶
const DefaultRubyVersion = "v0.1.0"
DefaultRubyVersion is the version of github.com/go-scikit/ruby a work module requires for its Ruby cells, unless Options.RubyVersion says otherwise.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Kernel ¶
type Kernel struct {
// contains filtered or unexported fields
}
Kernel runs one notebook.
type Options ¶
type Options struct {
// Dir is the work directory. It is created if needed.
Dir string
// Name is the notebook's file name, used in error positions.
Name string
// Replace adds replace directives to the work module, mapping a module
// path to a local directory (for a runtime or library under
// development).
Replace map[string]string
// RuntimeVersion is the version of github.com/go-notebook/notebook the
// work module requires. Empty means v0.0.0, which needs a Replace.
RuntimeVersion string
// RubyVersion is the version of github.com/go-scikit/ruby the work
// module requires when the notebook has Ruby cells; empty means
// DefaultRubyVersion.
RubyVersion string
// CellTimeout bounds how long one cell may run: a cell still running
// after it — an endless loop, in Go or in Ruby — has its worker killed
// and fails, and the next Run starts a new worker. Zero means no bound.
CellTimeout time.Duration
// CellMemory bounds, in bytes, the heap a worker's cells may hold. The
// Go garbage collector keeps under it as long as it can; a cell that
// holds more has its worker stopped and fails. Zero means no bound.
CellMemory int64
}
Options configure a Kernel.
type Report ¶
type Report struct {
Results []Result // one per code cell, in document order
Diags []gen.Diag
Built bool // whether the worker was rebuilt
Build time.Duration // how long generating and building took
}
Report is the outcome of a Run.
type Result ¶
type Result struct {
Cell int
Output string // what it printed
Display []map[string][]byte // what it showed
Error string // a compile error, a panic, or a failed input
Ran bool // it ran in this Run
Kept bool // its result was kept from before; neither means it did not run
Took time.Duration // how long it ran
}
Result is the outcome of one code cell.
Source Files