built-in REPL mode

Tips

go get and lgo

The packages you want to use in lgo must be prebuilt and installed into $LGOPATH by lgo install command.
Please make sure to run lgo install after you fetch a new package with go get command.

Update go version

Please run lgo install --clean after you update go version.

lgo install installs prebuilt packages into $LGOPATH.
When you update go version, you need to reinstall these prebuilt packages with the newer go
because binary formats of prebuilt packages may change in the newer version of go.

Display HTML and images

Cancellation

In lgo, you can interrupt execution by pressing "Stop" button (or pressing I, I) in Jupyter Notebook and pressing Ctrl-C in the interactive shell.

However, as you may know, Go does not allow you to cancel running goroutines with Ctrl-C. Go does not provide any API to cancel specific goroutines. The standard way to handle cancellation in Go today is to use context.Context (Read Go Concurrency Patterns: Context if you are not familiar with context.Context in Go).

lgo creates a special context _ctx on every execution and _ctx is cancelled when the execution is cancelled. Please pass _ctx as a context.Context param of Go libraries you want to cancel. Here is an example notebook of cancellation in lgo.

Memory Management

In lgo, memory is managed by the garbage collector of Go. Memory not referenced from any variables or goroutines is collected and released automatically.

One caveat of memory management in lgo is that memory referenced from global variables are not released automatically when the global variables are shadowed by other global variables with the same names. For example, if you run the following code blocks, the 32MB RAM reserved in [1] is not released after executing [2] and [3] because

[2] does not reset the value of b in [1]. It just defines another global variable b with the same name and shadows the reference to the first b.

[3] resets b defined in [2]. The memory reserved in [2] will be released after [3]. But the memory reserved in [1] will not be released.

Comparisons with similar projects

gore

gore, which was released in Feb 2015, is the most famous REPL implementation for Go as of Dec 2017. gore is a great tool to try out very short code snippets in REPL style.

But gore does not fit to data science or heavy data processing at all.
gore executes your inputs by concatinating all of your inputs,
wrapping it with main function and running it with go run command.
This means every time you input your code, gore executes all your inputs from the begining.
For example, if you are writing something like

gore always runs the first step when you calculate something and you need to wait for 1 min every time.
This behavior is not acceptable for real data science works. Also, gore is not good at tyring code with side effects (even fmt.Println) because code snippets with side effects are executed repeatedly and repeatedly.
lgo chose a totally different approach to execute Go code interactively and does not have the same shortcoming.

gophernotes was the first Jupyter kernel for Go, released in Jan 2016.
Before Sep 2017, it used the same technology gore uses to evaluate Go code. This means it did not fit to heavy data processing or data analysis at all.
From Sep 2017, gophernotes switched from go run approach to gomacro, one of unofficial golang interpreters by cosmos72. This solved the problem gore has. Now, the code execution mechnism of gophernotes also fits to heavy data analysis.

The shortcomings of using an unofficial interpreter are

It does not support all Go language features. Especially, it does not support one of the most important Go feature, interface.
As of go1.10, it is hard to support interface in an interpreter written in Go because of the lack of API in reflect package.

Interpreters are generally slow.

Unofficial interpreters are not well-tested compared to the official gc (go compiler) tools.

The advantages of this approach are

The overhead of code execution is small because it does not compile and link code.

Windows/Mac partial support. lgo works only on Linux and you need to use VMs or Docker to run it on Windows/Mac.
gophernotes (gomacro) works on Windows/Mac natively if you do not need third-party packages.

These disadvantage and advantages are not something inevitable in interperters. But they are not easy to solve under the limited development resource.

Also, lgo kernel supports more rich features in Jupyter Notebook as of Dec 2017, including code completion, code inspection and images/HTML/JavaScript output supports.

Troubleshooting

Dead kernel

Symptom

Got an error message like:

Kernel Restarting
The kernel appears to have died. It will restart automatically.

Solutions

First, please confirm your code does not call os.Exit directly or indirectly.
In lgo, your code is executed in the processs of lgo kernel. If you evaluate os.Exit in lgo, it terminates the lgo kernel process and jupyter notebook server loses the connection with the kernel.
Thus, you must not evaluate os.Exit or functions that call it internally (e.g. log.Fatal) in lgo.

If os.Exit is not the reason of "Dead kernel", please check crash logs of the kernel.
If you run your notebook with jupyter notebook command in a terminal, the crash log should be there.
If you run your notebook in docker, attach the container's terminal with docker attach to view the logs.
If you can see the logs of jupyter notebook, you should see logs like

multiple roots

Sympton

Solutions

This error occurs when the go command you are currently using is different from the go command you used to run lgo install.
For example, this happens if you update go from 1.9 to 1.10 but did not run lgo install --clean with the new go after the update.

If you encouter this issue, please double-check that you are using go which you used to run lgo install to install packages into $LGOPATH.