diff --git a/content/en/r.md b/content/en/r.md index 31416bf..6dd2248 100644 --- a/content/en/r.md +++ b/content/en/r.md @@ -1,22 +1,64 @@ --- title: "R cells" weight: 27 -description: "A ```r block is an R cell: parsed and checked with go-embedded-r's parser, its names in the dependency graph — but not run yet." +description: "A ```r block is an R cell: parsed with go-embedded-r's parser, run on its evaluator in one shared environment, and bounded in memory, steps and time." tags: [cells, r] --- -A ` ```r ` block is an R cell (go-notebook v0.8.0 and later). R cells are -**parsed and checked, but not run yet**: -[go-embedded-r](https://github.com/go-embedded-r/r), the pure-Go R these -cells are written for, has a complete parser today (its v0.1.0), and its -evaluator is the next milestones (M2 and M3). +A ` ```r ` block is an R cell (parsed since go-notebook v0.8.0, run since +v0.10.0). The R is [go-embedded-r](https://github.com/go-embedded-r/r), a +pure-Go R: go-notebook starts no external `R`. Its parser checks the cell and +its evaluator runs it. Since v0.12.0 every R cell is bounded (see +[Limits](#limits)). -## What works +```r +xs <- c(2.1, 3.4, 1.9, 5.6) +total <- sum(xs) +total / length(xs) +``` + +## Running + +**One environment.** The R cells of a notebook share one global environment, +so a variable assigned in one cell is there in the next, as in an R console. +A cell re-runs only when it or an R cell it reads changes. + +**Output.** What a cell prints is its output, as an R console shows it: +`print`, `cat`, and the value of every visible top-level expression. An +invisible value (`x <- 1`, `invisible(x)`) prints nothing. `message()` output +and the cell's warnings go to the standard error, the warnings in R's own form +(`Warning message:` then `In f(x) : text`; `Warning messages:` and a numbered +line each when there are several). An error fails the cell as +`Error in f(x) : text`, after the output written before it, and the cells that +read it do not run. A cell that goes over a limit fails the same way. + +A cell shows text only, no figure. + +## Limits + +A notebook may come from anyone, so each R cell runs with its own bounds: + +| Limit | Default | Ends a cell with | +| --- | --- | --- | +| memory | 512 MiB of vectors allocated in total over the cell, garbage included | `Error: memory limit exceeded: more than 536870912 bytes of vectors allocated` | +| steps (calls plus loop iterations) | 50 million | `Error: evaluation step limit reached` | +| time | 30 s | `stopped: the R cell ran longer than 30s, the limit` | -**Parsing.** An R cell is parsed by go-embedded-r's port of R 4.6's grammar, -which gives the same trees and tokens as R 4.6.2 on all of R's own -`src/library` and `tests` (932 files). A syntax error is reported at the -notebook's line and column, with R's own message: +The step count is measured: `for (i in 1:n) s <- s + i` stops at 16,666,666 +iterations under 50 million steps, so a simulation of that size runs and an +endless loop ends in seconds. The session and its variables survive a limit. + +A program that embeds the kernel can change them with `kernel.Options.R`: a +zero field is the default, and `-1` is no bound. `--timeout` and `--memory` +apply to R cells as to every cell, and they kill the worker, session +included. + +## Parsing + +An R cell is parsed by go-embedded-r's port of R 4.6's grammar, which gives +the same trees and tokens as R 4.6.2 on all of R's own `src/library` and +`tests` (932 files). A syntax error is reported at the notebook's line and +column, with R's own message: ````markdown ```r @@ -36,9 +78,10 @@ The parse is bounded (4 MiB per cell, a nesting depth of 1000, a million nodes), so a notebook from anyone cannot make it run long or exhaust memory; a cell over the limits fails with a message saying so. -**Names.** An R cell joins the [rules of cells](cells.md) and the dependency -graph. Its names follow R's scoping at the top level of the environment the -cell runs in: +## Names + +An R cell joins the [rules of cells](cells.md) and the dependency graph. Its +names follow R's scoping at the top level of the environment the cell runs in: | Construct | In the notebook | | --- | --- | @@ -56,64 +99,15 @@ cell runs in: on every cell before it, and every later cell that reads a name depends on it, so nothing it may define is missed. -**Across languages.** An R cell's variables are seen by Go, Ruby and Julia -cells, and an R cell sees theirs, as between Ruby and Go (see -[Ruby cells](ruby.md)); a function assigned at the top level stays in R. A -variable named like a Go keyword (`type`) is not seen by Go cells. - -## What does not work yet: running - -Running an R cell fails, clearly, and the cells that need it say why: - -````markdown -```go -n := 10 -``` - -```r -square <- function(v) v^2 -total <- sum(square(seq_len(n))) -``` - -```go -total + 1 -``` - -```go -n * 2 -``` -```` - -```console -$ notebook run r.md -── cell 0 (line 4, ran in 11µs) -── cell 1 (line 8, not run) - error: R cells are parsed and checked, but not run yet: execution arrives with go-embedded-r's evaluator (milestones M2 and M3) -── cell 2 (line 13, not run) - error: blocked: it depends on cell 1, an R cell, and R cells are not run yet -── cell 3 (line 17, ran in 24µs) - 20 -notebook: 2 cell(s) failed -``` - -(Real transcripts, from go-notebook v0.8.0.) - -- an R cell never runs, and `notebook run` exits non-zero; -- every cell that reads what an R cell defines, directly or through other - cells, in any language, is **blocked**, not silently skipped; -- the other cells run as usual. - -go-notebook starts no external `R`: the cells will run on go-embedded-r's own -evaluator when it exists. The HTML page shows an R cell's source uncoloured -(go-rouge has no R lexer). +**R variables stay in R.** They are not shared with Go, Ruby, Julia or C cells +in either direction yet: a Go cell that reads an R name finds it undefined, +and an R cell does not see a Go variable. ## In the browser -The [playground](https://go-notebook.github.io/playground/) (v0.9.0 and later) -parses and checks R cells in the same way, in WebAssembly: the + menu and the -cell's language menu offer R, its badge reads **R · not runnable yet**, a -syntax error is shown at its line in R's words, and the cells that read it -are blocked, in the page's neutral style and not as failures. - -The playground's R example notebook (`#5-r`) has an R cell, a Go cell blocked -on it and a Go cell that runs alone. +The [playground](https://go-notebook.github.io/playground/) does not run R +cells: its WebAssembly cores do not link the evaluator. It parses and checks +them: the + menu and the cell's language menu offer R, its badge reads +**R · not runnable yet**, a syntax error is shown at its line in R's words, +and the cells that read it are blocked, in the page's neutral style and not as +failures. Run the notebook with `notebook run` to execute its R cells.