Run V8 on separate thread (#325)

Rationale, implementation and known bugs are documented in DESIGN.md
but the elevator pitch is that Ruby and V8 don't like sharing the same
system stack.

mini_racer_extension.cc has been split into mini_racer_extension.c
and mini_racer_v8.cc. The former deals with Ruby, the latter with JS.

This work has been sponsored by Discourse.

Author: bnoordhuis

DESIGN.md

@@ -0,0 +1,93 @@
+rationale
+=========
+
+Before the commit that added this document, Ruby and V8 shared the same system
+stack but it's been observed that they don't always co-exist peacefully there.
+
+Symptoms range from unexpected JS stack overflow exceptions and hitting debug
+checks in V8, to outright segmentation faults.
+
+To mitigate that, V8 runs on separate threads now.
+
+implementation
+==============
+
+Each `MiniRacer::Context` is paired with a native system thread that runs V8.
+
+Multiple Ruby threads can concurrently access the `MiniRacer::Context`.
+MiniRacer ensures mutual exclusion. Ruby threads won't trample each other.
+
+Ruby threads communicate with the V8 thread through a mutex-and-condition-variable
+protected request/response memory buffer.
+
+The wire format is V8's native (de)serialization format. An encoder/decoder
+has been added to MiniRacer.
+
+Requests and (some) responses are prefixed with a single character
+that indicates the desired action: `'C'` is `context.call(...)`,
+`'E'` is `context.eval(...)`, and so on.
+
+A response from the V8 thread either starts with:
+
+- `'\xff'`, indicating a normal response that should be deserialized as-is
+
+- `'c'`, signaling an in-band request (not a response!) to call a Ruby function
+  registered with `context.attach(...)`. In turn, the Ruby thread replies with
+  a `'c'` response containing the return value from the Ruby function.
+
+Special care has been taken to ensure Ruby and JS functions can call each other
+recursively without deadlocking. The Ruby thread uses a recursive mutex that
+excludes other Ruby threads but still allows reentrancy from the same thread.
+
+The exact request and response payloads are documented in the source code but
+they are almost universally:
+
+- either a single value (e.g. `true` or `false`), or
+
+- a two or three element array (ex. `[filename, source]` for `context.eval(...)`), or
+
+- for responses, an errback-style `[response, error]` array, where `error`
+  is a multi-line string that contains the error message on the first line,
+  and, optionally, the stack trace. If not empty, the error string is turned
+  into a Ruby exception and raised.
+
+deliberate changes & known bugs
+===============================
+
+- `MiniRacer::Platform.set_flags! :single_threaded` still runs everything on
+  the same thread but is prone to crashes in Ruby < 3.4.0 due to a Ruby runtime
+  bug that clobbers thread-local variables.
+
+- The `Isolate` class is gone. Maintaining a one-to-many relationship between
+  isolates and contexts in a multi-threaded environment had a bad cost/benefit
+  ratio. `Isolate` methods like `isolate.low_memory_notification` have been
+  moved to `Context`, ex., `context.low_memory_notification`.
+
+- The `marshal_stack_depth` argument is still accepted but ignored; it's no
+  longer necessary.
+
+- The `ensure_gc_after_idle` argument is a no-op in `:single_threaded` mode.
+
+- The `timeout` argument no longer interrupts long-running Ruby code. Killing
+  or interrupting a Ruby thread executing arbitrary code is fraught with peril.
+
+- Returning an invalid JS `Date` object (think `new Date(NaN)`) now raises a
+  `RangeError` instead of silently returning a bogus `Time` object.
+
+- Not all JS objects map 1-to-1 to Ruby objects. Typed arrays and arraybuffers
+  are currently mapped to `Encoding::ASCII_8BIT`strings as the closest Ruby
+  equivalent to a byte buffer.
+
+- Not all JS objects are serializable/cloneable. Where possible, such objects
+  are substituted with a cloneable representation, else a `MiniRacer::RuntimeError`
+  is raised.
+
+  Promises, argument objects, map and set iterators, etc., are substituted,
+  either with an empty object (promises, argument objects), or by turning them
+  into arrays (map/set iterators.)
+
+  Function objects are substituted with a marker so they can be represented
+  as `MiniRacer::JavaScriptFunction` objects on the Ruby side.
+
+  SharedArrayBuffers are not cloneable by design but aren't really usable in
+  `mini_racer` in the first place (no way to share them between isolates.)

ext/mini_racer_extension/extconf.rb

@@ -1,5 +1,7 @@
 require 'mkmf'
 
+$srcs = ["mini_racer_extension.c", "mini_racer_v8.cc"]
+
 if RUBY_ENGINE == "truffleruby"
   File.write("Makefile", dummy_makefile($srcdir).join(""))
   return