Add JSRT basic tasks tutorials #44

liminzhu · 2017-11-17T22:26:25Z

Per #5, I'm adding some tutorials for JSRT. I'm putting the content in JSRT Overview before I find a better spot (feel free to make suggestions).

This PR adds illustration for

Expose native functions / external objects to JavaScript
Script serialization with lazy source loading
Call functions - Run a specified function in js file using ChakraCore? chakra-core/ChakraCore#2365 (comment)

And another temporary section for

Set up ES6 modules

liminzhu · 2017-11-17T22:27:40Z

@dilijev fyi

dilijev

LGTM modulo comments

dilijev · 2017-11-21T01:22:45Z

JavaScript-Runtime-(JSRT)-Overview.md

@@ -85,9 +85,117 @@ All other supported ES2015 features do not require any setup to run in JSRT.

 Features based on promises, such as [ES2016/ES7 Async Functions](https://blogs.windows.com/msedgedev/2015/09/30/asynchronous-code-gets-easier-with-es2016-async-function-support-in-chakra-and-microsoft-edge/), would require setting up promises before usage. 

+## Modules
+ES6 Modules are supported in ChakraCore. However, the host needs to specify how to resolve a module specifier since this part is host-specific not runtime-related. JSRT provides experimental APIs to set up ES6 modules. This [PR](https://github.com/Microsoft/ChakraCore/commit/50767f9f33812b4a036794a6a98404145563409f) gives you an overview of the related APIs and an example implementation (see WScriptJsrt.cpp) in the ch test host. Better documentation will be provided in the future.
+


For the PR you might want to link to the actual PR instead of the commit

chakra-core/ChakraCore#1254

dilijev · 2017-11-21T01:24:09Z

JavaScript-Runtime-(JSRT)-Overview.md

+	}
+	wprintf(L"\n");
+	return JS_INVALID_REFERENCE;
+}


The code above uses tabs while the rest uses 4 spaces. We use 4 spaces in ChakraCore so we should probably unify to that.

dilijev · 2017-11-21T01:24:54Z

JavaScript-Runtime-(JSRT)-Overview.md

+        // load script when necessary
+        *scriptBuffer = LoadScript(((SerializedSourceContext*)sourceContext)->scriptPath);
+        return true;
+    },


Should this whole block (starting from open brace line 186) be indented one level deeper (to line up with [] starting the lambda)?

dilijev · 2017-11-21T01:25:00Z

JavaScript-Runtime-(JSRT)-Overview.md

+        [](JsSourceContext sourceContext)
+    {
+        // free resources
+    },


Same comment re indentation.

dilijev · 2017-11-21T01:25:58Z

JavaScript-Runtime-(JSRT)-Overview.md

+JsSetProperty(global, consolePropId, console, true);
+```
+
+Now in JavaScript, you can do,


nit: change the trailing , to :

nit: also add a newline before the code block

dilijev · 2017-11-21T01:27:44Z

JavaScript-Runtime-(JSRT)-Overview.md

+console.log('Hello world');
+```
+
+If you need to expose an object that hosts data not directly exposed to JS, you can create an external object via `JsCreateExternalObject`.


Should we show an example of this?

I feel like the API shape is pretty self-explanatory so I left that out.

I'm not sure that this line is helpful without an example at least illustrating what type of data you might expose and why you might expose it.

Please also consider that we have JsCreateExternalObjectWithPrototype . IMHO we may show an example of that one instead (usage is available under test/native-tests)

@obastemur I didn't know that's a thing! Will look into it.

dilijev · 2017-11-21T01:31:35Z

JavaScript-Runtime-(JSRT)-Overview.md

+
+### Script serialization with lazy source loading  
+
+To support startup and execution efficiency, JSRT APIs provide the capability of pre-parsing, generating syntax trees and caching the bytecode for scripts. It is especially useful for server scenarios where the same script could get executed for thousands of times.


nit: executed for thousands of times -> executed thousands of times

dilijev · 2017-11-21T01:32:09Z

JavaScript-Runtime-(JSRT)-Overview.md

+
+The basic idea is to use variants of `JsSerializeScript` to parse and store the bytecode and then use `JsParse/RunSerializedScript` to parse or run the bytecode. Source is typically not needed for running serialized code, therefore you can also lazy-load the source script using `JsRunSerialized/JsRunSerializedScriptWithCallback`.
+
+


nit: remove extra newline

dilijev · 2017-11-21T01:33:43Z

JavaScript-Runtime-(JSRT)-Overview.md

+    JsValueRef result;
+    unsigned long bufferSize = 0;
+    BYTE *buffer = nullptr;
+    JsSerializeScript(script, buffer, &bufferSize); // get correct buffer size


nit: to make this clearer (passing nullptr for buffer argument to get size without filling a buffer or getting an error about buffer too small), replace buffer with nullptr in this line.

dilijev · 2017-11-21T01:37:05Z

JavaScript-Runtime-(JSRT)-Overview.md

+        [](JsSourceContext sourceContext, const WCHAR** scriptBuffer)
+    {
+        // load script when necessary
+        *scriptBuffer = LoadScript(((SerializedSourceContext*)sourceContext)->scriptPath);


Are LoadScript and LoadByteCode visible to user code through JSRT or are these stubs not defined in this example?

They are pseudo-code methods user need to define

liminzhu · 2017-11-22T19:04:22Z

Thanks for the comments @dilijev !

kfarnung · 2017-11-23T00:41:01Z

JavaScript-Runtime-(JSRT)-Overview.md

+        JsConvertValueToString(arguments[index], &stringValue);
+        const wchar_t *string;
+        size_t length;
+        JsStringToPointer(stringValue, &string, &length);


Do we want these examples to also work cross-plat? For instance JsStringToPointer isn't exposed on Linux/Mac, instead JsCopyString needs to be used.

kfarnung · 2017-11-23T00:43:16Z

JavaScript-Runtime-(JSRT)-Overview.md

+// create console object, log function, and set log function as property of console
+JsCreateObject(&console);
+JsCreateFunction(LogCB, nullptr, &logFunc);
+JsGetPropertyIdFromName(L"log", &logPropId);


JsGetPropertyIdFromName is also only available on Windows, JsCreatePropertyId should be used instead.

kfarnung

LGTM keeping in mind that the examples will only run on Windows. I'd recommend that another pass it made to ensure that all examples work cross-platform.

obastemur · 2017-11-23T08:35:31Z

JavaScript-Runtime-(JSRT)-Overview.md

+    JsValueRef result;
+    unsigned long bufferSize = 0;
+    BYTE *buffer = nullptr;
+    JsSerializeScript(script, nullptr, &bufferSize); // get correct buffer size


This is also not ChakraCore. Use JsSerialize please.

liminzhu · 2017-11-28T00:06:48Z

I will crossplat-fy all the samples. Thanks for the suggestion @kfarnung @obastemur .

dilijev · 2017-12-04T19:39:30Z

JavaScript-Runtime-(JSRT)-Overview.md

 }

-// load and run bytecode 
-void runSerializeScript(const wchar_t *bytecodeBufferPath, const wchar_t *scriptBufferPath) {
+   // load and run bytecode 


nit: looks like accidental space

liminzhu · 2017-12-05T22:01:04Z

All feedback addressed and ready to merge if yall have no additional feedback. Thanks guys!

dilijev approved these changes Nov 21, 2017

View reviewed changes

kfarnung reviewed Nov 23, 2017

View reviewed changes

kfarnung approved these changes Nov 23, 2017

View reviewed changes

obastemur reviewed Nov 23, 2017

View reviewed changes

dilijev reviewed Dec 4, 2017

View reviewed changes

Add JSRT basic tasks tutorials

c3cdad5

liminzhu force-pushed the howto branch from 5b42098 to c3cdad5 Compare December 5, 2017 21:59

liminzhu force-pushed the master branch from 4e3c30c to e9a0bdc Compare December 6, 2017 20:55

liminzhu merged commit 9b41859 into microsoft:master Dec 6, 2017

dilijev mentioned this pull request Dec 6, 2017

Documentation Improvements: How to do basic things with ChakraCore #5

Open

13 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add JSRT basic tasks tutorials #44

Add JSRT basic tasks tutorials #44

liminzhu commented Nov 17, 2017

liminzhu commented Nov 17, 2017

dilijev left a comment

dilijev Nov 21, 2017

dilijev Nov 21, 2017

dilijev Nov 21, 2017

dilijev Nov 21, 2017

dilijev Nov 21, 2017

dilijev Nov 21, 2017

dilijev Nov 21, 2017

liminzhu Nov 22, 2017

kfarnung Nov 23, 2017

obastemur Nov 23, 2017

liminzhu Nov 28, 2017 •

edited

Loading

dilijev Nov 21, 2017

dilijev Nov 21, 2017

dilijev Nov 21, 2017

dilijev Nov 21, 2017

liminzhu Nov 22, 2017

liminzhu commented Nov 22, 2017

kfarnung Nov 23, 2017 •

edited

Loading

kfarnung Nov 23, 2017

kfarnung left a comment

obastemur Nov 23, 2017

liminzhu commented Nov 28, 2017

dilijev Dec 4, 2017

liminzhu commented Dec 5, 2017


		### Script serialization with lazy source loading

		To support startup and execution efficiency, JSRT APIs provide the capability of pre-parsing, generating syntax trees and caching the bytecode for scripts. It is especially useful for server scenarios where the same script could get executed for thousands of times.


		The basic idea is to use variants of `JsSerializeScript` to parse and store the bytecode and then use `JsParse/RunSerializedScript` to parse or run the bytecode. Source is typically not needed for running serialized code, therefore you can also lazy-load the source script using `JsRunSerialized/JsRunSerializedScriptWithCallback`.

Add JSRT basic tasks tutorials #44

Add JSRT basic tasks tutorials #44

Conversation

liminzhu commented Nov 17, 2017

liminzhu commented Nov 17, 2017

dilijev left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liminzhu Nov 28, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liminzhu commented Nov 22, 2017

kfarnung Nov 23, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kfarnung left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liminzhu commented Nov 28, 2017

Choose a reason for hiding this comment

liminzhu commented Dec 5, 2017

liminzhu Nov 28, 2017 •

edited

Loading

kfarnung Nov 23, 2017 •

edited

Loading