From 01448d53fcfa525e1c291f946c7a933cf026a5d7 Mon Sep 17 00:00:00 2001 From: Ivan Daniluk Date: Wed, 13 Sep 2017 16:27:19 +0200 Subject: [PATCH] Update jail docs (#313) --- geth/jail/README.md | 29 +++++++++++++++++------------ geth/jail/doc.go | 10 ++++------ 2 files changed, 21 insertions(+), 18 deletions(-) diff --git a/geth/jail/README.md b/geth/jail/README.md index 504271f1a..169e26f39 100644 --- a/geth/jail/README.md +++ b/geth/jail/README.md @@ -1,10 +1,11 @@ -# Jail +# Package Jail + +[![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/jail?status.svg)](https://godoc.org/github.com/status-im/status-go/geth/jail) + -- import "github.com/status-im/status-go/geth/jail" -go:generate godocdown -heading Title -o README.md - Package jail implements "jailed" enviroment for executing arbitrary JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto). @@ -27,7 +28,7 @@ Otto virtual machine and lives forever, but that may change in the future. ### Cells Each Cell object embeds *VM from 'jail/vm' for concurrency safe wrapper around -*otto.VM functions. This important when dealing with setTimeout and Fetch API +*otto.VM functions. This is important when dealing with setTimeout and Fetch API functions (see below). @@ -49,9 +50,9 @@ for execution, Call takes a JS function name (defined in VM) and parameters. Default Otto VM interpreter doesn't support setTimeout()/setInterval() JS functions, because they're not part of ECMA-262 spec, but properties of the -window object in browser. We add support for them using -http://github.com/status-im/ottoext/timers and -http://github.com/status-im/ottoext/loop packages. +window object in browser. We add support for them using own implementation of +Event Loop, heavily based on http://github.com/status-im/ottoext package. See +loop/fetch/promise packages under `jail/internal/`. Each cell starts a new loop in a separate goroutine, registers functions for setTimeout/setInterval calls and associate them with this loop. All JS code @@ -75,17 +76,17 @@ In order to capture response one may use following approach: ### Fetch support -Fetch API is implemented using http://github.com/status-im/ottoext/fetch -package. When Cell is created, corresponding handlers are registered within VM -and associated event loop. +Fetch API is implemented in a similar way using the same loop. When Cell is +created, corresponding handlers are registered within VM and associated event +loop. Due to asynchronous nature of Fetch API, the following code will return immediately: cell.Run(`fetch('http://example.com/').then(function(data) { ... })`) -### and callback function in a promise will be executed in a event loop in the -backgrounds. Thus, it's user responsibility to register a corresponding callback +and callback function in a promise will be executed in a event loop in the +background. Thus, it's user responsibility to register a corresponding callback function before: cell.Set("__captureSuccess", func(res otto.Value) { ... }) @@ -96,3 +97,7 @@ function before: // user code __captureSuccess(data) })) + +### Package documentation + +See: [![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/jail?status.svg)](https://godoc.org/github.com/status-im/status-go/geth/jail) \ No newline at end of file diff --git a/geth/jail/doc.go b/geth/jail/doc.go index b52af0966..c2194b5be 100644 --- a/geth/jail/doc.go +++ b/geth/jail/doc.go @@ -21,7 +21,7 @@ Otto virtual machine and lives forever, but that may change in the future. Cells Each Cell object embeds *VM from 'jail/vm' for concurrency safe wrapper around -*otto.VM functions. This important when dealing with setTimeout and Fetch API +*otto.VM functions. This is important when dealing with setTimeout and Fetch API functions (see below). Get and Set @@ -40,8 +40,7 @@ Timeouts and intervals support Default Otto VM interpreter doesn't support setTimeout()/setInterval() JS functions, because they're not part of ECMA-262 spec, but properties of the window object in browser. -We add support for them using http://github.com/status-im/ottoext/timers and http://github.com/status-im/ottoext/loop -packages. +We add support for them using own implementation of Event Loop, heavily based on http://github.com/status-im/ottoext package. See loop/fetch/promise packages under `jail/internal/`. Each cell starts a new loop in a separate goroutine, registers functions for setTimeout/setInterval calls and associate them with this loop. All JS code executed as callback to setTimeout/setInterval @@ -64,14 +63,13 @@ In order to capture response one may use following approach: Fetch support -Fetch API is implemented using http://github.com/status-im/ottoext/fetch package. When -Cell is created, corresponding handlers are registered within VM and associated event loop. +Fetch API is implemented in a similar way using the same loop. When Cell is created, corresponding handlers are registered within VM and associated event loop. Due to asynchronous nature of Fetch API, the following code will return immediately: cell.Run(`fetch('http://example.com/').then(function(data) { ... })`) -and callback function in a promise will be executed in a event loop in the backgrounds. Thus, +and callback function in a promise will be executed in a event loop in the background. Thus, it's user responsibility to register a corresponding callback function before: cell.Set("__captureSuccess", func(res otto.Value) { ... })