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.2.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 ¶
var CompleteTimeout = 5 * time.Second
CompleteTimeout bounds how long a completion may take: the worker of a session whose completion runs longer (a receiver whose #methods does not return) is stopped, as a timed-out input's is.
Functions ¶
This section is empty.
Types ¶
type Evaluation ¶ added in v0.5.0
type Evaluation struct {
Inspect string // the value, as irb shows it
Display map[string][]byte // the value's own display (a figure's SVG), if any
Error string // the exception, "message (Class)" and its frames, or why the input was stopped
Class string // the exception's class (SystemExit for exit)
Lost bool // the input's worker was stopped: the session's state is gone
Notice string // why an earlier worker stopped between inputs, if one did
Took time.Duration // how long the input ran, in the worker
}
Evaluation is the outcome of one input.
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.
type Session ¶ added in v0.5.0
type Session struct {
// contains filtered or unexported fields
}
Session is an interactive Ruby session, as irb is (notebook irb): inputs evaluated one at a time in one interpreter, any local assigned as often as wanted, `_` the last value. The interpreter runs in a worker process of its own, built once in the work directory, so an input that runs too long or holds too much memory (Options.CellTimeout and CellMemory, which apply to each input), or that is interrupted, has its worker killed while the session goes on — with a new worker, the state of the old one lost.
A Session is not safe for concurrent use, except Interrupt, which may be called from another goroutine (a signal handler) while Eval runs.
func NewSession ¶ added in v0.5.0
NewSession prepares a session in opt.Dir — writing and building its worker when the work module is new or has changed, which progress is told about — and starts the worker. The kernel's other options apply as for a notebook: the runtime and go-scikit/ruby versions, the replaced modules, the limits.
func (*Session) Complete ¶ added in v0.5.0
Complete returns the completions of target, the word before the cursor; none when the worker cannot say. A completion that takes longer than CompleteTimeout stops the worker, and the next Eval says so.
func (*Session) Eval ¶ added in v0.5.0
func (s *Session) Eval(src string, line int, output func(string)) Evaluation
Eval evaluates one input, which starts at line of the session (the line numbers of its backtraces), and hands what it prints to output as it is printed. A worker that a previous input or completion stopped is replaced first.
Source Files