nathanaela / v8-natives

Access v8 Engine Natives easily in Chrome & Node

v8-Natives

Updated:

Last Tested on Node 14 & Chrome 80+

Access v8 Engine Natives easily in Chrome & Node

I was reading a blog/wiki article at https://github.com/petkaantonov/bluebird/wiki/Optimization-killers and it presents some really low level diagnostic commands that I was totally unaware of; and so I found them to be totally awesome in scope for several things I do. The V8 engine has a large array of commands that you can call that can get and/or set status in the actual v8 engine. This library is my attempt to make my life a lot easier and eliminate the errors in trying to use the v8 native commands. These low level commands allow you access to tell the v8 engine to optimize a routine and then find out if a routine can/is optimized.

Now, you can call the v8 native commands directly (for example %CollectGarbage()); however if you forget to use the --allow-natives-syntax then the v8 engine will immediately stop parsing the file as the v8 commands all start with a '%' which is invalid JavaScript... What this library does is it is a simple wrapper that wraps those calls; so that I can do (v8.CollectGarbage()). If you forgot the --allow-natives-syntax it will still run your code fine; it just won't do anything.

In the examples folder is a browser example; to show you how it works in Chrome/Chromium (chrome --js-flags="--allow-natives-syntax" browser.html). You can run it in a non-v8 browser and it will just use the dummy shim.
In addition there is a NodeJS example to show you the same support in NodeJS. (node --allow-natives-syntax node.js)

Please note the examples and helper commands can show you how to use a good chunk of the optimization, general and Memory calls in the library. If someone wants to work up some examples using the variable/object information commands; they would gladly be accepted!

Installing V8 Natives

npm install v8-natives

Breaking changes

Removed from recent versions of V8

• setFlags
• getV8Version

Renamed in v8

• functionGetName = getFunctionName

Usage

Browser:

<script src="v8-browser.js" onload="waitForV8(some_callback)"></script>
<script>function some_callback() { 
  v8.collectGarbage(); 
  /* more v8.commands */}
</script>

Node:

var v8 = require('v8-natives');   
v8.collectGarbage(); 
/* more v8 commands */

Commands

Helper Commands

• helpers.testOptimization(func[, funcNames]) - This will automatically call the function once, call the optimizeOnNextCall; call the function again, and then call printStatus on the function. You can also do: testOptimization([func1, func2, func3]) this is so that if you have func1 which called func2 & func3 you can see if all three get optimized. It will automatically call func1, set the optimization flag on all three funcs, and then call func1 and then printStatus on all three funcs.
• helpers.printStatus(func) - Prints the function optimization results to the console
• helpers.benchmark(count, func) - Runs a func in a loop count times. This will automatically set the optimization flag; run it count times, run garbageCollection start the time; run func for count times; and then return the total time taken.
• window.waitForV8(callback) - [Browser ONLY]; this will wait until the v8 namespace is loaded properly and then call your callback.

General Commands

• isNative() - Is the Native Support mode enabled (i.e. true = uses real wrapper; false = use dummy wrapper)
• functionGetName(func) - Gets the string name of a function

Memory Commands

• getHeapUsage() - Shows how much heap is used
• collectGarbage() - Force a full Garbage Collection

Optimization Commands

• deoptimizeNow -
• optimizeFunctionOnNextCall(func) - Tells v8 to optimizes the function the next time you call it
• deoptimizeFunction(func) - De-optimize a function
• neverOptimizeFunction(func) - Never Optimize a function
• getOptimizationStatus(func) - Get the functions optimization status [1 = Optimized, 2 = Un-optimized, 3 = Always Optimized, 4 = Never Optimized, 5 = ?, 6 = Maybe Optimized] I've only seen 1 & 2 from my tests; but according to the blog/wiki article I read 3, 4 & 6 are valid also)

Variable/Object information Commands

• hasFastProperties(obj)
• hasFastSmiElements(obj)
• hasFastObjectElements(obj)
• hasFastDoubleElements(obj)
• hasDictionaryElements(obj)
• hasFastHoleyElements(obj)
• haveSameMap(obj1, obj2)
• isValidSmi(obj)
• isSmi(obj)
• hasFastSmiOrObjectElements(obj)
• hasSloppyArgumentsElements(obj)

Notes

optimizedFunctionOnNextCall(func) needs the function ran before it can tag it for optimization. So the procedure is:

• Run your function
• Run your function (Have to do this TWICE)
• Tag your function for optimization
• Run your Function
• Verify that the v8 Engine optimized it. If it did not optimized it; then that means you have code that can't be optimized in it.

ChangeLog

v8 Internal function list has changed the following functions have been removed:

• getOptimizationCount

v8 Renamed:

• ClearFunctionTypeFeedback to ClearFunctionFeedback

v8-natives's Issues

broken in Node 6.0

Error info:

        return %IsInPrototypeChain(value, proto);
                                               ^
SyntaxError: IsInPrototypeChain is not defined

testOptimization: 2 calls are needed to go from uninitialized -> pre-monomorphic -> monomorphic

Hi,

See this comment in:
https://github.com/petkaantonov/bluebird/wiki/Optimization-killers#1-tooling

So perhaps better run the functions twice in testOptimization before the check?

Thanks!

getOptimizationStatus

From looking at the source code for getOptimizationStatus, it looks like the values below can be returned. It also looks like it takes 1 or 2 arguments, the first being the function, of course, the second being a boolean that tells V8 to sync with the compilation thread or not. The default is true but can be set to false, making this call a bit faster (but probably less reliable in terms of the validity of its reply).

Return values:

• 1 - Yes
• 2 - No
• 3 - Always
• 4 - Never
• 5 - ??? Don't see it returned at all
• 6 - Maybe de-optimized
• 7 - TurboFan compiler

Here's the function source code from v8/src/runtime/runtime-test.cc:

RUNTIME_FUNCTION(Runtime_GetOptimizationStatus) {
  HandleScope scope(isolate);
  RUNTIME_ASSERT(args.length() == 1 || args.length() == 2);
  if (!isolate->use_crankshaft()) {
    return Smi::FromInt(4);  // 4 == "never".
  }
  bool sync_with_compiler_thread = true;
  if (args.length() == 2) {
    CONVERT_ARG_HANDLE_CHECKED(String, sync, 1);
    if (sync->IsOneByteEqualTo(STATIC_CHAR_VECTOR("no sync"))) {
      sync_with_compiler_thread = false;
    }
  }
  CONVERT_ARG_HANDLE_CHECKED(JSFunction, function, 0);
  if (isolate->concurrent_recompilation_enabled() &&
      sync_with_compiler_thread) {
    while (function->IsInOptimizationQueue()) {
      isolate->optimizing_compile_dispatcher()->InstallOptimizedFunctions();
      base::OS::Sleep(base::TimeDelta::FromMilliseconds(50));
    }
  }
  if (FLAG_always_opt || FLAG_prepare_always_opt) {
    // With --always-opt, optimization status expectations might not
    // match up, so just return a sentinel.
    return Smi::FromInt(3);  // 3 == "always".
  }
  if (FLAG_deopt_every_n_times) {
    return Smi::FromInt(6);  // 6 == "maybe deopted".
  }
  if (function->IsOptimized() && function->code()->is_turbofanned()) {
    return Smi::FromInt(7);  // 7 == "TurboFan compiler".
  }
  return function->IsOptimized() ? Smi::FromInt(1)   // 1 == "yes".
                                 : Smi::FromInt(2);  // 2 == "no".
}

Smi, by the way, is small integer. An isolate is a sanboxed instance of V8.

Anyway, this isn't really an "issue", just wanted to clarify your documentation. Also, there's lots to learn from looking through the v8/src/runtime/ directory but bear in mind that the V8 source code is gnarly, badly formatted, everything's poorly named, and there are practically no comments. :) That being said, some pretty smart code in there.

Julian

%GetHeapUsage removed

It looks like %GetHeapUsage is no longer available in Chrome 91, which is unfortunate since the code is using it to test for --allow-natives-syntax support.

I can't find anything official on when it was removed or why, but:

In strict mode: ReferenceError: v8 is not defined

Hi,

First off, this is a very useful wrapper with helpers, thanks a lot!

As I run all my code in strict mode I got the following error:

c:\teki\nodejs\node_modules\v8-natives\lib\v8-node.js:28                              
    v8 = require('./v8-native-calls.js').v8;                                          
       ^                                                                              
ReferenceError: v8 is not defined                                                     
    at Object.<anonymous> (c:\teki\nodejs\node_modules\v8-natives\lib\v8-node.js:28:8)
    at Module._compile (module.js:456:26)                                             
    at Object.Module._extensions..js (module.js:474:10)                               
    at Module.load (module.js:356:32)                                                 
    at Function.Module._load (module.js:312:12)                                       
    at Module.require (module.js:364:17)                                              
    at require (module.js:380:17)                                                     
    at Object.<anonymous> (C:\teki\www\test\test\scad\tests\js\solids\test.js:1:72)   
    at Module._compile (module.js:456:26)                                             
    at Object.Module._extensions..js (module.js:474:10)                               

I've just added var v8; on line 26 of file v8-node.js and all seems to be well, or is there something not good with my node installation?

I develop all in Windows (as you probably can see on the paths).

Cornelis.

Programmatically taking heap snapshots

Stumbled across repo, looks very interesting.

Chrome's heap snapshots and heap profiling provide lots of useful information:

https://developers.google.com/web/tools/chrome-devtools/profile/memory-problems/heap-snapshots

We want to be able to:

• programmatically take snapshots and profiles and
• make assertions about object count, shallow size and retained size for these snapshots/profiles

Can you help to point us in the right direction?

Thanks

Tried you module in the browser and could not get it to work

Your module was linked to in an answer to a question I published on the stack overflow forum. In an answer to my own question, I documented what it was I tried, and which did not work. Here is the link.

https://stackoverflow.com/questions/58861823/can-i-turn-off-optimization-so-in-scope-variables-from-closures-arent-optimiz

Awesome timing

I was just reading bluebird paper as well and was looking for a better alternative than shoving native syntax inside production code. thanks.

btw, is there any way I can pass in parameters to the function that is going to be tested for arguments?

`isObserved` and `getThreadCount` deprecated?

Hello -

Were those two methods deprecated in a later version of Node (> 7)? I got undefined errors when requiring v8-natives, and the problem was fixed by commenting those definitions out in the source.

Unable to run browser example with Chrome 62.0.3202 on MacOS 10.13

Here are my steps:

git clone
alias chrome="/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome"
cd examples
chrome --js-flags="--allow-natives-syntax" browser.html

Is there anything else I should know about? I've tried many variations of flags. The node variant works for me, but not the browser variant. It does enable %GetOptimizationStatus(). %FunctionGetName(), but not %GetV8Version() and %GetOptimizationCount().