← Back to branch summary

~ubuntu-branches/ubuntu/saucy/nodejs/saucy-proposed

« back to all changes in this revision

Viewing changes to doc/api/vm.markdown

  • Committer: Package Import Robot
  • Author(s): Jérémy Lal
  • Date: 2013-08-14 00:16:46 UTC
  • mfrom: (7.1.40 sid)
  • Revision ID: package-import@ubuntu.com-20130814001646-bzlysfh8sd6mukbo
Tags: 0.10.15~dfsg1-4
* Update 2005 patch, adding a handful of tests that can fail on
  slow platforms.
* Add 1004 patch to fix test failures when writing NaN to buffer
  on mipsel.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/api/vm.markdown
1
1
# Executing JavaScript
2
2
 
3
 
    Stability: 3 - Stable
 
3
    Stability: 2 - Unstable. See Caveats, below.
4
4
 
5
5
<!--name=vm-->
6
6
 
10
10
 
11
11
JavaScript code can be compiled and run immediately or compiled, saved, and run later.
12
12
 
 
13
## Caveats
 
14
 
 
15
The `vm` module has many known issues and edge cases. If you run into
 
16
issues or unexpected behavior, please consult [the open issues on
 
17
GitHub](https://github.com/joyent/node/issues?labels=vm&state=open).
 
18
Some of the biggest problems are described below.
 
19
 
 
20
### Sandboxes
 
21
 
 
22
The `sandbox` argument to `vm.runInNewContext` and `vm.createContext`,
 
23
along with the `initSandbox` argument to `vm.createContext`, do not
 
24
behave as one might normally expect and their behavior varies
 
25
between different versions of Node.
 
26
 
 
27
The key issue to be aware of is that V8 provides no way to directly
 
28
control the global object used within a context. As a result, while
 
29
properties of your `sandbox` object will be available in the context,
 
30
any properties from the `prototype`s of the `sandbox` may not be
 
31
available. Furthermore, the `this` expression within the global scope
 
32
of the context evaluates to the empty object (`{}`) instead of to
 
33
your sandbox.
 
34
 
 
35
Your sandbox's properties are also not shared directly with the script.
 
36
Instead, the properties of the sandbox are copied into the context at
 
37
the beginning of execution, and then after execution, the properties
 
38
are copied back out in an attempt to propagate any changes.
 
39
 
 
40
### Globals
 
41
 
 
42
Properties of the global object, like `Array` and `String`, have
 
43
different values inside of a context. This means that common
 
44
expressions like `[] instanceof Array` or
 
45
`Object.getPrototypeOf([]) === Array.prototype` may not produce
 
46
expected results when used inside of scripts evaluated via the `vm` module.
 
47
 
 
48
Some of these problems have known workarounds listed in the issues for
 
49
`vm` on GitHub. for example, `Array.isArray` works around
 
50
the example problem with `Array`.
13
51
 
14
52
## vm.runInThisContext(code, [filename])
15
53
 
95
133
    // { animal: 'cat', count: 3, name: 'CATT' }
96
134
 
97
135
Note that `createContext` will perform a shallow clone of the supplied sandbox object in order to
98
 
initialise the global object of the freshly constructed context.
 
136
initialize the global object of the freshly constructed context.
99
137
 
100
138
Note that running untrusted code is a tricky business requiring great care.  To prevent accidental
101
139
global variable leakage, `vm.runInContext` is quite useful, but safely running untrusted code