Update documentation for execution timeout feature

Author: cowboyd

Changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Current
+
+* add `timeout` option to `V8::Context` to forcibly abort long running scripts (thanks to @SamSaffron)
+
+## 0.12.0 2013/08/20
+
+* upgrade v8 to 3.16.4 (thanks to @ignisf)
+* enable native (and functional) weakref implementation for MRI > 2.0
+* expose low level interface for `V8::C::HeapStatistics#total_physical_size`
+
 ## 0.11.1 2013/01/04
 
 * reintroduce the dependency on libv8

README.md

@@ -125,6 +125,32 @@ behavior you'd like.
 
 More documentation can be found on the [GitHub wiki](https://github.com/cowboyd/therubyracer/wiki)
 
+### Protecting Your CPU cycles
+
+When running untrusted JavaScript code, you not only have to protect
+which functions it has access to, but also how much of your CPU it can
+consume. Take this simple, yet thoroughly malicious script:
+
+```javascript
+while (true) {}
+```
+
+It will loop forever and never return control to the calling Ruby
+thread. To protect against such JavaScript code that either
+deliberately or accidentally runs longer that it should, you can
+set an explicit timeout on your context. If the code runs longer that
+the allowed timeout, then it will throw an exception. Note that this
+exception could be raised at any point in the execution of the
+JavaScript.
+
+To specify the timeout (in milliseconds), pass in the `timeout` option
+to the constructor.
+
+```ruby
+cxt = V8::Context.new timeout: 700
+cxt.eval "while (true);" #= exception after 700ms!
+```
+
 ### PREREQUISITES
 
 The Ruby Racer requires the V8 Javascript engine, but it offloads the
@@ -173,4 +199,4 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 [1]: https://github.com/cowboyd/libv8
-[2]: http://code.google.com/p/v8/wiki/BuildingWithGYP
+[2]: http://code.google.com/p/v8/wiki/BuildingWithGYP

lib/v8/context.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 require 'stringio'
 module V8
   # All JavaScript must be executed in a context. This context consists of a global scope containing the
@@ -39,7 +40,8 @@ class Context
     #   @return [V8::C::Context] the underlying C++ object
     attr_reader :native
 
-    # maximum execution time for script in milliseconds
+    # @!attribute [r] timeout
+    #   @return [Number] maximum execution time in milliseconds for scripts executed in this context
     attr_reader :timeout
 
     # Creates a new context.