As a few people have noticed, we took a small breaking change to the JsRT API between the Windows 8.1 Preview and Windows 8.1 RTM. The JsCreateFunction API got an additional parameter that allows registering a piece of data (which can just be null) with the native callback which will be provided to the callback when it’s invoked. It’s a super-useful place to stash something like a “this” pointer for a C++ callback, which is why we added it before the concrete completely dried on the API. It does mean, though, that most applications compiled against the preview will break and need to be recompiled against RTM.

Accordingly, we’ve updated both the MSDN documentation for JSRT and the Code Gallery hosting sample.

You can always reach me on Twitter here.

The last major conceptual topic to cover for JsRT is how exceptions are handled.

Internally, Chakra uses C++ exception handling to handle both JavaScript exceptions and internal engine exceptions. However, even though the host might also be using C++ exception handling, the JsRT API surface enforces a strict separation between the host and Chakra when it comes to exceptions. Chakra exceptions will never cross over into the host (i.e. they will always be caught at the API boundary), and host exceptions should never cross over into the Chakra engine. Thus, hosts need to guard any callbacks to ensure that internal host exceptions don’t escape into Chakra.

OK, so, then how do exceptions work?

When a JavaScript exception occurs during script execution or during script compilation, and the exception is not handled in the script itself (i.e. the exception makes it to a JsRT API boundary), the containing runtime is put into an exception state. While in the exception state, no code can run in the runtime and all API calls will fail (with the error code JsErrorInExceptionState). This will continue until the host retrieves and clears the exception using the JsGetAndClearException API. This API will return an object representing the JavaScript value thrown (or the compile exception if the error occurred during compilation), and the runtime will be free to run code. How the host handles the exception is up to the host.

If the host is in the middle of a callback from Chakra, the host can also just return from the callback without clearing the runtime from an exception state. This will cause the JavaScript exception to be re-thrown when control passes back to the JavaScript engine.

If the host is in the middle of a callback and wants to “throw” a JavaScript exception, it can set the runtime into an exception state using JsSetException and then return from the callback. Just as above, the exception will be thrown in JavaScript once control passes back to the Chakra engine.

You should also follow me on Twitter here.

Yikes! It’s been longer than I thought it’s been since I last wrote on JsRT. Sorry about that, we’ve been a little busy.

With the two major concepts, runtimes and contexts, covered, there were a few additional things that need to be addressed for hosts that want to use JsRT. Probably the most important is how memory management is coordinated between Chakra and the host.

As you know, JavaScript is a garbage collected language, and everything you allocate through the JsRT API (with the exception of runtimes) is managed by the Chakra garbage collector. References will continue to live only as long as the garbage collector thinks they are “alive.” Once the GC thinks a reference is dead, the next collection will free up the memory and the reference will become invalid. The garbage collector looks in two places when determining if a reference is alive:

1. The runtime’s garbage collected heap.
2. The stack of the runtime’s current thread.

So a reference to a JavaScript value that is stored inside of another JavaScript value or in a local variable on the stack will always be seen by the garbage collector. But if a host stores a reference somewhere where the GC isn’t going to look (for example, in a host-allocated heap), then the reference will not be seen by the garbage collector and may result in premature collection of values that are still in use by the host. (When relying on a stack reference to keep a reference alive, you have to be extra careful–some language compilers (such as VC++) will optimize away stack variables where possible.)

If a host is going to store a reference where the GC can’t see it, it will need to manually add a reference to the object itself by calling JsAddRef. This will ensure the object will not go away until JsRelease is called. Calls to JsAddRef/JsRelease have to be paired–unbalanced calls will result in objects being collected too soon or staying alive forever.

You should also follow me on Twitter here.

With the release of the IE11 Developer Preview for Windows 7, the JsRT APIs are now also available on Windows 7! Just install the developer preview on a Windows 7 machine and any app that’s compiled against the JsRT APIs will now run…

You should also follow me on Twitter here.

Last time, I covered runtimes, this time I want to briefly cover execution contexts. While a runtime owns all the machinery needed to execute code (heap, GC, JIT, etc.), it can’t just execute code on its own–it has to execute the code within a particular context. Each context shares its resources with other contexts in the runtime, but it has one crucial thing all to itself–the global object and everything that sits under it. So while code executed in two contexts that belong to the same runtime may use the same heap, they are nonetheless unable to see or affect one another at the language level. Contexts are effectively totally isolated from each other. Because objects created in a context are tied to that context’s unique global object, an object created in one context cannot be passed in to another context. The JsRT APIs check all incoming objects to ensure that they match the context being used and will error if they don’t.

To simplify the JsRT API, most of the APIs assume an ambient execution context. Once you set the current context on a thread using JsSetCurrentContext, all APIs will assume that context until you call JsSetCurrentContext again (APIs will return a JsErrorNoCurrentContext error if there isn’t a context that’s been set current on the thread). Contexts are tied to their parent runtime’s thread–making a context current on a thread means that that runtime becomes current on that thread. If the runtime happens to be active on another thread at the time, then setting the current context will fail.

Within a thread, however, calls into contexts can be nested. So, for example, a runtime r1 can create two contexts c1 and c2. It can then run a script in c1 which calls back into the host. The host callback can then set c2 as the current context and run some more code, provided that it restores c1 as the current context when it’s done. So it’s legal to run code in c2 while c1 is on the stack, you just have to make sure that you clean up when you’re done.

Finally, from a host’s perspective the most important thing to remember regarding contexts is that if you have host objects that you want to project into the JavaScript space for scripts to use, you have to do it for each context you create. There’s currently no way to say something like, “I want this object to appear in all contexts I create.”

You should also follow me on Twitter here.

Now that the sample is out, I wanted to take a few posts to walk through some of the basics of hosting the Chakra engine in your application. Some of this will repeat the MSDN documentation a bit, but I’ll try and expand on some of the details.

The base entity in the JsRT API is a runtime. A runtime represents a complete JavaScript execution environment, including a garbage collected heap (with it’s own garbage collector) and just-in-time (JIT) native code compiler. So two different runtimes will have separate heaps and separate JITs, and will not share any memory or generated native code. They are entirely separate from one another.

Runtimes represent a single thread of execution, so more than one runtime can be active at the same time within a process, but within a runtime there will only ever be one active thread of execution. Runtimes are not tied to a particular system thread, however, but are rental threaded. That means that a runtime can move from one system thread to another provided that the runtime is not currently executing any code. So while a runtime is running code (or is in a host callback while running code), it cannot be moved to another thread. But if it’s not running anything, the host is free to use that runtime on another thread. This means that if a runtime isn’t active for some reason (maybe it’s waiting for something to happen), the thread is free to run something in another runtime.

When creating a runtime, a number of choices can be made about the behavior of the runtime. The most important is how background work will be done. By default, creating a runtime will create two additional threads: a GC thread for the garbage collector and JIT thread for the native code compiler. These threads allow garbage collection and JIT compilation to happen in the background while code is running in the foreground. There are two other configurations possible, though. If you don’t want any background work done, you can specify the JsRuntimeAttributeDisableBackgroundWork flag, and all GC and JIT work will be done on the foreground on demand. Or you can choose to run the background work yourself by passing in a JsThreadServiceCallback routine when you create the runtime. In that case, the runtime will call the callback when it has GC or JIT work that needs to be done. The callback can either run the work on any thread it likes, or it can return false, meaning that the work should just be run on the foreground thread. Using a callback allows a host to pool GC and JIT threads across runtimes, for example.

Code that is running inside a runtime can be interrupted by calling JsDisableRuntimeExecution. The way that interruption works is that all code compiled by the runtime inserts calls to a check routine that will fail if execution has been disabled. So code will continue to run, even after the disable API has been called, until it hits one of these checks. By default, these checks are fairly conservative to avoid impacting performance too much. In particular, we don’t insert checks in loops by default. This means you don’t have any additional overhead when running a tight loop, but it also means that if you happen to hit an infinite loop, your script will hang and will not be interruptible. If you specify the JsRuntimeAttributeAllowScriptInterrupt flag, the runtime will insert additional script interruption checks into places like the bottom of loops so that script interruption becomes more reliable, at the cost of some small amount of performance.

There are some bookkeeping tasks that the runtime may need to do, particularly in longer-running runtimes. For example, if a lot of memory has been freed up by the GC, it can be advantageous to decommit memory pages that are no longer in use, freeing them up for use by the system. This kind of work is what we consider “idle” work, and if your host is long running enough, there can be benefit in passing in the JsRuntimeEnableIdleProcessing flag and then periodically calling the JsIdle API when the host is idle. If idle processing isn’t enabled and we need to do some bookkeeping work, we’ll typically do that when a script finishes running.

And, finally, there may be situations where a host might want to turn off some of the runtime capabilities for safety or security. If you don’t want scripts you run to be able to dynamically run code (i.e. call eval or the function constructor), you can specify the JsRuntimeAttributeDisableEval flag. If you don’t want the JIT compiler to generate native code, and instead just run everything under the interpreter (for example, if you have some concern about native code generation in your process), you can specify the JsRuntimeAttributeDisableNativeCodeGeneration flag. This last flag should be used with a great deal of caution–as you can imagine, JITted code is vastly more efficient than interpreted byte codes, so you’ll pay a significant penalty for turning off the JIT. Use only when absolutely necessary.

The last thing you can choose when creating a runtime is the version of the language you want. This is fairly straightforward–you can pick IE10 (corresponds to ES5), IE11 (ES5 + some ES6 features + some compatibility features like __proto__), or “edge” which will give you the latest version. The edge version will float, so be warned–if your host is run on some future platform with some version higher than IE11 (whatever that will be), you’ll get that newest version. Caveat emptor.

I think that about covers it for runtimes. Up next will be execution contexts…

You should also follow me on Twitter here.

After sorting out some kinks in the process, the samples and documentation for JsRT (the new hosting API for the Chakra JavaScript engine) are now online. You can find them here:

• MSDN documentation
• Code Gallery hosting sample

There’s one more sample I need to get up that shows how to map the heap enumeration API to JSON such that Visual Studio 2013 preview can open it in its memory analysis tool. That should be coming shortly. I’ve also got a few other things in the pipeline. If there’s anything in particular you’d like to see, leave a comment or hit me up on Twitter!

You can always reach me on Twitter here.

One of the most exciting things about the JavaScript language in the past few years has been the way it which it has been making a leap beyond the browser. The world generally under-appreciates the power of small, high-embeddable, and interactive languages, and it’s been heartening to see the great work of the node.js crew and others using JS for a wide variety of non-browser application. Lots of applications and platforms have hidden value inside of them that is almost entirely inaccessible until someone like JavaScript comes along and unlocks them, enabling regular people to do things that can almost seem magical. (I saw a lot of this early on in my career working on Access, which combined the power of a relational database with embedded BASIC.) It’s what drew me to the Chakra JavaScript runtime team a little over a year ago, when I was given the opportunity to explore some ideas around making JavaScript embeddable on the Windows platform.

Actually, I can hear some of you saying, “Hey, wait a minute! You can already embed JavaScript on Windows! You just use the IActiveScript APIs. Everybody knows that!” That’s true, but the IActiveScript APIs have two problems:

1. They are COM based and require extensive use of IDispatch for communication between the JavaScript host and JavaScript code (which is an issue both in terms of coding and performance).
2. They only work with the JavaScript engine that last shipped with IE8 (a.k.a. the “legacy engine”). The new Chakra engine, which has a high-performance GC and JIT compiler, does not officially support the IActiveScript interfaces. It talks to IE using a set of private (and IE-specific) interfaces.

However, I’m proud to announce that, as of the IE11 preview (released at build last week), Chakra now has a fully supported public API! It’s called the “JsRT API” (for “JavaScript RunTime API”) and it enables any application running on Windows to use the Chakra JavaScript engine. The APIs are all  regular Win32 APIs and are designed for ease-of-use and high-performance applications. Here are some technical details:

• The JsRT APIs are part of IE11 and will be supported on any operating system that has IE11 installed on it. RIght now, that means Windows 8.1 and Windows Server 2012 R2. Once IE11 is released for them, it will also mean Windows 7 and Windows Server 2008 R2.
• The Windows 8.1 SDK (included with the Visual Studio 2013 preview) includes the new header file jsrt.h and export library file jsrt.lib which you can use to compile against in C/C++ projects.
• We don’t have an official CLR wrapper at this point, but we will be providing a code sample shortly that wraps all the JsRT APIs with P/Invoke calls.
• The JsRT APIs are not supported in Windows Runtime applications. Because the Windows Runtime itself hosts Chakra, there are a number of important technical issues having to do with the way the system hosting and application hosting could interact that need to be solved. We won’t have solutions for these issues in the Windows 8.1 timeframe, unfortunately.

We’ll also be putting up code samples that show off all the basics of hosting Chakra, including some side benefits that you get for free from the rest of the Microsoft ecosystem:

• The Visual Studio script debugger (or, really, any IActiveScript debugger) will work with a Chakra host. This includes breakpoints, locals inspection, stepping, etc. as well as some exciting new features for IE11 that I’ll talk about later.
• The Visual Studio 2013 preview profiler will work with a Chakra host out of the box to profile JavaScript code.
• The Visual Studio 2013 preview JavaScript memory analyzer will work with a Chakra host as well.

As you can see, there are a lot of capabilities available when you use Chakra inside of your application. This is just the introductory post, I’ll be talking in more detail in the coming weeks about all the cool things you can do with the runtime. But in the meantime, download the Windows 8.1 preview and the Visual Studio 2013 preview and get cracking!

You can always reach me on Twitter here.