status-im
/
status-go
mirror of https://github.com/status-im/status-go.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update jail docs (#313)

This commit is contained in:
Ivan Daniluk 2017-09-13 16:27:19 +02:00 committed by Ivan Tomilov
parent 3109656014
commit 01448d53fc
2 changed files with 21 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
geth/jail/README.md
View File

@ -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" 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 Package jail implements "jailed" enviroment for executing arbitrary JavaScript
code using Otto JS interpreter (https://github.com/robertkrimen/otto). 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 ### Cells
Each Cell object embeds *VM from 'jail/vm' for concurrency safe wrapper around 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). 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 Default Otto VM interpreter doesn't support setTimeout()/setInterval() JS
functions, because they're not part of ECMA-262 spec, but properties of the functions, because they're not part of ECMA-262 spec, but properties of the
window object in browser. We add support for them using window object in browser. We add support for them using own implementation of
http://github.com/status-im/ottoext/timers and Event Loop, heavily based on http://github.com/status-im/ottoext package. See
http://github.com/status-im/ottoext/loop packages. loop/fetch/promise packages under `jail/internal/`.
Each cell starts a new loop in a separate goroutine, registers functions for 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 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 support
Fetch API is implemented using http://github.com/status-im/ottoext/fetch Fetch API is implemented in a similar way using the same loop. When Cell is
package. When Cell is created, corresponding handlers are registered within VM created, corresponding handlers are registered within VM and associated event
and associated event loop. loop.
Due to asynchronous nature of Fetch API, the following code will return Due to asynchronous nature of Fetch API, the following code will return
immediately: immediately:
cell.Run(`fetch('http://example.com/').then(function(data) { ... })`) cell.Run(`fetch('http://example.com/').then(function(data) { ... })`)
### and callback function in a promise will be executed in a event loop in the 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 background. Thus, it's user responsibility to register a corresponding callback
function before: function before:
cell.Set("__captureSuccess", func(res otto.Value) { ... }) cell.Set("__captureSuccess", func(res otto.Value) { ... })
@ -96,3 +97,7 @@ function before:
// user code // user code
__captureSuccess(data) __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)

10
geth/jail/doc.go
View File

@ -21,7 +21,7 @@ Otto virtual machine and lives forever, but that may change in the future.
Cells Cells
Each Cell object embeds *VM from 'jail/vm' for concurrency safe wrapper around 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). functions (see below).
Get and Set Get and Set
@ -40,8 +40,7 @@ Timeouts and intervals support
Default Otto VM interpreter doesn't support setTimeout()/setInterval() JS functions, 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. 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 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/`.
packages.
Each cell starts a new loop in a separate goroutine, registers functions for setTimeout/setInterval 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 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 support
Fetch API is implemented using http://github.com/status-im/ottoext/fetch package. When 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.
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: Due to asynchronous nature of Fetch API, the following code will return immediately:
cell.Run(`fetch('http://example.com/').then(function(data) { ... })`) 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: it's user responsibility to register a corresponding callback function before:
cell.Set("__captureSuccess", func(res otto.Value) { ... }) cell.Set("__captureSuccess", func(res otto.Value) { ... })