//-------------------------------------------------------------------------------------------------------

// Copyright (C) Microsoft. All rights reserved.

// Licensed under the MIT license. See LICENSE.txt file in the project root for full license information.

//-------------------------------------------------------------------------------------------------------

/// \mainpage Chakra Hosting API Reference

///

/// Chakra is Microsoft's JavaScript engine. It is an integral part of Internet Explorer but can

/// also be hosted independently by other applications. This reference describes the APIs available

/// to applications to host Chakra.

///

/// This file contains the common API set shared among all Chakra releases. For Windows-specific

/// releases, see chakrart.h.

/// \file

/// \brief The base Chakra hosting API.

///

/// This file contains a flat C API layer. This is the API exported by chakra.dll.

#ifdef _MSC_VER

#pragma once

#endif // _MSC_VER

#ifndef _CHAKRACOMMON_H_

#define _CHAKRACOMMON_H_

// Platform specific code

#if defined(_WIN32) && defined(_MSC_VER)

#include <windows.h>

// Header macros

#define CHAKRA_CALLBACK CALLBACK

#define CHAKRA_API STDAPI_(JsErrorCode)

typedef unsigned char byte;

typedef DWORD_PTR ChakraCookie;

typedef BYTE* ChakraBytePtr;

#else // Non-Windows VC++

// SAL compat

#define _Return_type_success_(x)

#define _In_

#define _In_z_

#define _In_opt_

#define _Inout_

#define _Inout_opt_

#define _Out_

#define _Out_opt_

#define _In_reads_(x)

#define _Pre_maybenull_

#define _Pre_writable_byte_size_(byteLength)

#define _Outptr_result_buffer_(byteLength)

#define _Outptr_result_bytebuffer_(byteLength)

#define _Outptr_result_maybenull_

#define _Outptr_result_z_

#define _Ret_maybenull_

#define _Out_writes_(size)

#define _Out_writes_to_opt_(byteLength, byteLength2)

// Header macros

#ifdef __i386___

#define CHAKRA_CALLBACK __attribute__((cdecl))

#else // non-32 bit x86 doesn't have cdecl support

#define CHAKRA_CALLBACK

#endif // __i386__

#ifndef _WIN32

#define SET_API_VISIBILITY __attribute__((visibility("default")))

#else

#define SET_API_VISIBILITY

#endif

#ifdef __cplusplus

#define CHAKRA_API extern "C" SET_API_VISIBILITY JsErrorCode

#else

#define CHAKRA_API extern SET_API_VISIBILITY JsErrorCode

#include <stdbool.h>

#endif

#include <stddef.h> // for size_t

#include <stdint.h> // for uintptr_t

typedef uintptr_t ChakraCookie;

typedef unsigned char* ChakraBytePtr;

// xplat-todo: try reduce usage of following types

#if !defined(__MSTYPES_DEFINED)

typedef uint32_t UINT32;

typedef int64_t INT64;

typedef void* HANDLE;

typedef unsigned char BYTE;

typedef BYTE byte;

typedef UINT32 DWORD;

typedef unsigned short WCHAR;

#endif

#endif // defined(_WIN32) && defined(_MSC_VER)

#if (defined(_MSC_VER) && _MSC_VER <= 1900) || (!defined(_MSC_VER) && __cplusplus <= 199711L) // !C++11

typedef unsigned short uint16_t;

#else

#include <stdint.h>

#endif

/// <summary>

/// An error code returned from a Chakra hosting API.

/// </summary>

typedef _Return_type_success_(return == 0) enum _JsErrorCode

{

/// <summary>

/// Success error code.

/// </summary>

JsNoError = 0,

/// <summary>

/// Category of errors that relates to incorrect usage of the API itself.

/// </summary>

JsErrorCategoryUsage = 0x10000,

/// <summary>

/// An argument to a hosting API was invalid.

/// </summary>

JsErrorInvalidArgument,

/// <summary>

/// An argument to a hosting API was null in a context where null is not allowed.

/// </summary>

JsErrorNullArgument,

/// <summary>

/// The hosting API requires that a context be current, but there is no current context.

/// </summary>

JsErrorNoCurrentContext,

/// <summary>

/// The engine is in an exception state and no APIs can be called until the exception is

/// cleared.

/// </summary>

JsErrorInExceptionState,

/// <summary>

/// A hosting API is not yet implemented.

/// </summary>

JsErrorNotImplemented,

/// <summary>

/// A hosting API was called on the wrong thread.

/// </summary>

JsErrorWrongThread,

/// <summary>

/// A runtime that is still in use cannot be disposed.

/// </summary>

JsErrorRuntimeInUse,

/// <summary>

/// A bad serialized script was used, or the serialized script was serialized by a

/// different version of the Chakra engine.

/// </summary>

JsErrorBadSerializedScript,

/// <summary>

/// The runtime is in a disabled state.

/// </summary>

JsErrorInDisabledState,

/// <summary>

/// Runtime does not support reliable script interruption.

/// </summary>

JsErrorCannotDisableExecution,

/// <summary>

/// A heap enumeration is currently underway in the script context.

/// </summary>

JsErrorHeapEnumInProgress,

/// <summary>

/// A hosting API that operates on object values was called with a non-object value.

/// </summary>

JsErrorArgumentNotObject,

/// <summary>

/// A script context is in the middle of a profile callback.

/// </summary>

JsErrorInProfileCallback,

/// <summary>

/// A thread service callback is currently underway.

/// </summary>

JsErrorInThreadServiceCallback,

/// <summary>

/// Scripts cannot be serialized in debug contexts.

/// </summary>

JsErrorCannotSerializeDebugScript,

/// <summary>

/// The context cannot be put into a debug state because it is already in a debug state.

/// </summary>

JsErrorAlreadyDebuggingContext,

/// <summary>

/// The context cannot start profiling because it is already profiling.

/// </summary>

JsErrorAlreadyProfilingContext,

/// <summary>

/// Idle notification given when the host did not enable idle processing.

/// </summary>

JsErrorIdleNotEnabled,

/// <summary>

/// The context did not accept the enqueue callback.

/// </summary>

JsCannotSetProjectionEnqueueCallback,

/// <summary>

/// Failed to start projection.

/// </summary>

JsErrorCannotStartProjection,

/// <summary>

/// The operation is not supported in an object before collect callback.

/// </summary>

JsErrorInObjectBeforeCollectCallback,

/// <summary>

/// Object cannot be unwrapped to IInspectable pointer.

/// </summary>

JsErrorObjectNotInspectable,

/// <summary>

/// A hosting API that operates on symbol property ids but was called with a non-symbol property id.

/// The error code is returned by JsGetSymbolFromPropertyId if the function is called with non-symbol property id.

/// </summary>

JsErrorPropertyNotSymbol,

/// <summary>

/// A hosting API that operates on string property ids but was called with a non-string property id.

/// The error code is returned by existing JsGetPropertyNamefromId if the function is called with non-string property id.

/// </summary>

JsErrorPropertyNotString,

/// <summary>

/// Module evaluation is called in wrong context.

/// </summary>

JsErrorInvalidContext,

/// <summary>

/// The Module HostInfoKind provided was invalid.

/// </summary>

JsInvalidModuleHostInfoKind,

/// <summary>

/// Module was parsed already when JsParseModuleSource is called.

/// </summary>

JsErrorModuleParsed,

/// <summary>

/// Argument passed to JsCreateWeakReference is a primitive that is not managed by the GC.

/// No weak reference is required, the value will never be collected.

/// </summary>

JsNoWeakRefRequired,

/// <summary>

/// The <c>Promise</c> object is still in the pending state.

/// </summary>

JsErrorPromisePending,

/// <summary>

/// Module was not yet evaluated when JsGetModuleNamespace was called.

/// </summary>

JsErrorModuleNotEvaluated,

/// <summary>

/// Category of errors that relates to errors occurring within the engine itself.

/// </summary>

JsErrorCategoryEngine = 0x20000,

/// <summary>

/// The Chakra engine has run out of memory.

/// </summary>

JsErrorOutOfMemory,

/// <summary>

/// The Chakra engine failed to set the Floating Point Unit state.

/// </summary>

JsErrorBadFPUState,

/// <summary>

/// Category of errors that relates to errors in a script.

/// </summary>

JsErrorCategoryScript = 0x30000,

/// <summary>

/// A JavaScript exception occurred while running a script.

/// </summary>

JsErrorScriptException,

/// <summary>

/// JavaScript failed to compile.

/// </summary>

JsErrorScriptCompile,

/// <summary>

/// A script was terminated due to a request to suspend a runtime.

/// </summary>

JsErrorScriptTerminated,

/// <summary>

/// A script was terminated because it tried to use <c>eval</c> or <c>function</c> and eval

/// was disabled.

/// </summary>

JsErrorScriptEvalDisabled,

/// <summary>

/// Category of errors that are fatal and signify failure of the engine.

/// </summary>

JsErrorCategoryFatal = 0x40000,

/// <summary>

/// A fatal error in the engine has occurred.

/// </summary>

JsErrorFatal,

/// <summary>

/// A hosting API was called with object created on different javascript runtime.

/// </summary>

JsErrorWrongRuntime,

/// <summary>

/// Category of errors that are related to failures during diagnostic operations.

/// </summary>

JsErrorCategoryDiagError = 0x50000,

/// <summary>

/// The object for which the debugging API was called was not found

/// </summary>

JsErrorDiagAlreadyInDebugMode,

/// <summary>

/// The debugging API can only be called when VM is in debug mode

/// </summary>

JsErrorDiagNotInDebugMode,

/// <summary>

/// The debugging API can only be called when VM is at a break

/// </summary>

JsErrorDiagNotAtBreak,

/// <summary>

/// Debugging API was called with an invalid handle.

/// </summary>

JsErrorDiagInvalidHandle,

/// <summary>

/// The object for which the debugging API was called was not found

/// </summary>

JsErrorDiagObjectNotFound,

/// <summary>

/// VM was unable to perform the request action

/// </summary>

JsErrorDiagUnableToPerformAction,

/// <summary>

/// Serializer/Deserializer does not support current data

/// </summary>

JsSerializerNotSupported,

/// <summary>

/// Current object is not transferable during serialization

/// </summary>

JsTransferableNotSupported,

/// <summary>

/// Current object is already detached when serialized

/// </summary>

JsTransferableAlreadyDetached,

} JsErrorCode;

/// <summary>

/// A handle to a Chakra runtime.

/// </summary>

/// <remarks>

/// <para>

/// Each Chakra runtime has its own independent execution engine, JIT compiler, and garbage

/// collected heap. As such, each runtime is completely isolated from other runtimes.

/// </para>

/// <para>

/// Runtimes can be used on any thread, but only one thread can call into a runtime at any

/// time.

/// </para>

/// <para>

/// NOTE: A <c>JsRuntimeHandle</c>, unlike other object references in the Chakra hosting API,

/// is not garbage collected since it contains the garbage collected heap itself. A runtime

/// will continue to exist until <c>JsDisposeRuntime</c> is called.

/// </para>

/// </remarks>

typedef void *JsRuntimeHandle;

/// <summary>

/// An invalid runtime handle.

/// </summary>

#ifdef __cplusplus

const JsRuntimeHandle JS_INVALID_RUNTIME_HANDLE = 0;

#else

#define JS_INVALID_RUNTIME_HANDLE (JsRuntimeHandle)0

#endif

/// <summary>

/// A reference to an object owned by the Chakra garbage collector.

/// </summary>

/// <remarks>

/// A Chakra runtime will automatically track <c>JsRef</c> references as long as they are

/// stored in local variables or in parameters (i.e. on the stack). Storing a <c>JsRef</c>

/// somewhere other than on the stack requires calling <c>JsAddRef</c> and <c>JsRelease</c> to

/// manage the lifetime of the object, otherwise the garbage collector may free the object

/// while it is still in use.

/// </remarks>

typedef void *JsRef;

/// <summary>

/// An invalid reference.

/// </summary>

#ifdef __cplusplus

const JsRef JS_INVALID_REFERENCE = 0;

#else

#define JS_INVALID_REFERENCE (JsRef)0

#endif

/// <summary>

/// A reference to a script context.

/// </summary>

/// <remarks>

/// <para>

/// Each script context contains its own global object, distinct from the global object in

/// other script contexts.

/// </para>

/// <para>

/// Many Chakra hosting APIs require an "active" script context, which can be set using

/// <c>JsSetCurrentContext</c>. Chakra hosting APIs that require a current context to be set

/// will note that explicitly in their documentation.

/// </para>

/// </remarks>

typedef JsRef JsContextRef;

/// <summary>

/// A reference to a JavaScript value.

/// </summary>

/// <remarks>

/// A JavaScript value is one of the following types of values: undefined, null, Boolean,

/// string, number, or object.

/// </remarks>

typedef JsRef JsValueRef;

/// <summary>

/// A cookie that identifies a script for debugging purposes.

/// </summary>

typedef ChakraCookie JsSourceContext;

/// <summary>

/// An empty source context.

/// </summary>

#ifdef __cplusplus

const JsSourceContext JS_SOURCE_CONTEXT_NONE = (JsSourceContext)-1;

#else

#define JS_SOURCE_CONTEXT_NONE (JsSourceContext)-1

#endif

/// <summary>

/// A property identifier.

/// </summary>

/// <remarks>

/// Property identifiers are used to refer to properties of JavaScript objects instead of using

/// strings.

/// </remarks>

typedef JsRef JsPropertyIdRef;

/// <summary>

/// Attributes of a runtime.

/// </summary>

typedef enum _JsRuntimeAttributes

{

/// <summary>

/// No special attributes.

/// </summary>

JsRuntimeAttributeNone = 0x00000000,

/// <summary>

/// The runtime will not do any work (such as garbage collection) on background threads.

/// </summary>

JsRuntimeAttributeDisableBackgroundWork = 0x00000001,

/// <summary>

/// The runtime should support reliable script interruption. This increases the number of

/// places where the runtime will check for a script interrupt request at the cost of a

/// small amount of runtime performance.

/// </summary>

JsRuntimeAttributeAllowScriptInterrupt = 0x00000002,

/// <summary>

/// Host will call <c>JsIdle</c>, so enable idle processing. Otherwise, the runtime will

/// manage memory slightly more aggressively.

/// </summary>

JsRuntimeAttributeEnableIdleProcessing = 0x00000004,

/// <summary>

/// Runtime will not generate native code.

/// </summary>

JsRuntimeAttributeDisableNativeCodeGeneration = 0x00000008,

/// <summary>

/// Using <c>eval</c> or <c>function</c> constructor will throw an exception.

/// </summary>

JsRuntimeAttributeDisableEval = 0x00000010,

/// <summary>

/// Runtime will enable all experimental features.

/// </summary>

JsRuntimeAttributeEnableExperimentalFeatures = 0x00000020,

/// <summary>

/// Calling <c>JsSetException</c> will also dispatch the exception to the script debugger

/// (if any) giving the debugger a chance to break on the exception.

/// </summary>

JsRuntimeAttributeDispatchSetExceptionsToDebugger = 0x00000040,

/// <summary>

/// Disable Failfast fatal error on OOM

/// </summary>

JsRuntimeAttributeDisableFatalOnOOM = 0x00000080,

/// <summary>

/// Runtime will not allocate executable code pages

/// This also implies that Native Code generation will be turned off

/// Note that this will break JavaScript stack decoding in tools

// like WPA since they rely on allocation of unique thunks to

// interpret each function and allocation of those thunks will be

// disabled as well

/// </summary>

JsRuntimeAttributeDisableExecutablePageAllocation = 0x00000100,

} JsRuntimeAttributes;

/// <summary>

/// The type of a typed JavaScript array.

/// </summary>

typedef enum _JsTypedArrayType

{

/// <summary>

/// An int8 array.

/// </summary>

JsArrayTypeInt8,

/// <summary>

/// An uint8 array.

/// </summary>

JsArrayTypeUint8,

/// <summary>

/// An uint8 clamped array.

/// </summary>

JsArrayTypeUint8Clamped,

/// <summary>

/// An int16 array.

/// </summary>

JsArrayTypeInt16,

/// <summary>

/// An uint16 array.

/// </summary>

JsArrayTypeUint16,

/// <summary>

/// An int32 array.

/// </summary>

JsArrayTypeInt32,

/// <summary>

/// An uint32 array.

/// </summary>

JsArrayTypeUint32,

/// <summary>

/// A float32 array.

/// </summary>

JsArrayTypeFloat32,

/// <summary>

/// A float64 array.

/// </summary>

JsArrayTypeFloat64

} JsTypedArrayType;

/// <summary>

/// Allocation callback event type.

/// </summary>

typedef enum _JsMemoryEventType

{

/// <summary>

/// Indicates a request for memory allocation.

/// </summary>

JsMemoryAllocate = 0,

/// <summary>

/// Indicates a memory freeing event.

/// </summary>

JsMemoryFree = 1,

/// <summary>

/// Indicates a failed allocation event.

/// </summary>

JsMemoryFailure = 2

} JsMemoryEventType;

/// <summary>

/// Attribute mask for JsParseScriptWithAttributes

/// </summary>

typedef enum _JsParseScriptAttributes {

/// <summary>

/// Default attribute

/// </summary>

JsParseScriptAttributeNone = 0x0,

/// <summary>

/// Specified script is internal and non-user code. Hidden from debugger

/// </summary>

JsParseScriptAttributeLibraryCode = 0x1,

/// <summary>

/// ChakraCore assumes ExternalArrayBuffer is Utf8 by default.

/// This one needs to be set for Utf16

/// </summary>

JsParseScriptAttributeArrayBufferIsUtf16Encoded = 0x2,

/// <summary>

/// Script should be parsed in strict mode

/// </summary>

JsParseScriptAttributeStrictMode = 0x4,

} JsParseScriptAttributes;

/// <summary>

/// Type enumeration of a JavaScript property

/// </summary>

typedef enum _JsPropertyIdType {

/// <summary>

/// Type enumeration of a JavaScript string property

/// </summary>

JsPropertyIdTypeString,

/// <summary>

/// Type enumeration of a JavaScript symbol property

/// </summary>

JsPropertyIdTypeSymbol

} JsPropertyIdType;

/// <summary>

/// The JavaScript type of a JsValueRef.

/// </summary>

typedef enum _JsValueType

{

/// <summary>

/// The value is the <c>undefined</c> value.

/// </summary>

JsUndefined = 0,

/// <summary>

/// The value is the <c>null</c> value.

/// </summary>

JsNull = 1,

/// <summary>

/// The value is a JavaScript number value.

/// </summary>

JsNumber = 2,

/// <summary>

/// The value is a JavaScript string value.

/// </summary>

JsString = 3,

/// <summary>

/// The value is a JavaScript Boolean value.

/// </summary>

JsBoolean = 4,

/// <summary>

/// The value is a JavaScript object value.

/// </summary>

JsObject = 5,

/// <summary>

/// The value is a JavaScript function object value.

/// </summary>

JsFunction = 6,

/// <summary>

/// The value is a JavaScript error object value.

/// </summary>

JsError = 7,

/// <summary>

/// The value is a JavaScript array object value.

/// </summary>

JsArray = 8,

/// <summary>

/// The value is a JavaScript symbol value.

/// </summary>

JsSymbol = 9,

/// <summary>

/// The value is a JavaScript ArrayBuffer object value.

/// </summary>

JsArrayBuffer = 10,

/// <summary>

/// The value is a JavaScript typed array object value.

/// </summary>

JsTypedArray = 11,

/// <summary>

/// The value is a JavaScript DataView object value.

/// </summary>

JsDataView = 12,

} JsValueType;

typedef enum _JsScriptEncodingType

{

Utf8,

Utf16

} JsScriptEncodingType;

typedef enum _JsScriptContainerType

{

HeapAllocatedBuffer

} JsScriptContainerType;

typedef struct _JsScriptContents

{

void * container;

JsScriptEncodingType encodingType;

JsScriptContainerType containerType;

JsSourceContext sourceContext;

size_t contentLengthInBytes;

WCHAR * fullPath;

} JsScriptContents;

/// <summary>

/// User implemented callback routine for memory allocation events

/// </summary>

/// <remarks>

/// Use <c>JsSetRuntimeMemoryAllocationCallback</c> to register this callback.

/// </remarks>

/// <param name="callbackState">

/// The state passed to <c>JsSetRuntimeMemoryAllocationCallback</c>.

/// </param>

/// <param name="allocationEvent">The type of type allocation event.</param>

/// <param name="allocationSize">The size of the allocation.</param>

/// <returns>

/// For the <c>JsMemoryAllocate</c> event, returning <c>true</c> allows the runtime to continue

/// with the allocation. Returning false indicates the allocation request is rejected. The

/// return value is ignored for other allocation events.

/// </returns>

typedef bool (CHAKRA_CALLBACK * JsMemoryAllocationCallback)(_In_opt_ void *callbackState, _In_ JsMemoryEventType allocationEvent, _In_ size_t allocationSize);

/// <summary>

/// A callback called before collection.

/// </summary>

/// <remarks>

/// Use <c>JsSetBeforeCollectCallback</c> to register this callback.

/// </remarks>

/// <param name="callbackState">The state passed to <c>JsSetBeforeCollectCallback</c>.</param>

typedef void (CHAKRA_CALLBACK *JsBeforeCollectCallback)(_In_opt_ void *callbackState);

/// <summary>

/// A callback called before collecting an object.

/// </summary>

/// <remarks>

/// Use <c>JsSetObjectBeforeCollectCallback</c> to register this callback.

/// </remarks>

/// <param name="ref">The object to be collected.</param>

/// <param name="callbackState">The state passed to <c>JsSetObjectBeforeCollectCallback</c>.</param>

typedef void (CHAKRA_CALLBACK *JsObjectBeforeCollectCallback)(_In_ JsRef ref, _In_opt_ void *callbackState);

/// <summary>

/// A background work item callback.

/// </summary>

/// <remarks>

/// This is passed to the host's thread service (if provided) to allow the host to

/// invoke the work item callback on the background thread of its choice.

/// </remarks>

/// <param name="callbackState">Data argument passed to the thread service.</param>

typedef void (CHAKRA_CALLBACK *JsBackgroundWorkItemCallback)(_In_opt_ void *callbackState);

/// <summary>

/// A thread service callback.

/// </summary>

/// <remarks>

/// The host can specify a background thread service when calling <c>JsCreateRuntime</c>. If

/// specified, then background work items will be passed to the host using this callback. The

/// host is expected to either begin executing the background work item immediately and return

/// true or return false and the runtime will handle the work item in-thread.

/// </remarks>

/// <param name="callback">The callback for the background work item.</param>

/// <param name="callbackState">The data argument to be passed to the callback.</param>

typedef bool (CHAKRA_CALLBACK *JsThreadServiceCallback)(_In_ JsBackgroundWorkItemCallback callback, _In_opt_ void *callbackState);

/// <summary>

/// Called by the runtime when it is finished with all resources related to the script execution.

/// The caller should free the source if loaded, the byte code, and the context at this time.

/// </summary>

/// <param name="sourceContext">The context passed to Js[Parse|Run]SerializedScriptWithCallback</param>

typedef void (CHAKRA_CALLBACK * JsSerializedScriptUnloadCallback)(_In_ JsSourceContext sourceContext);

/// <summary>

/// A finalizer callback.

/// </summary>

/// <param name="data">

/// The external data that was passed in when creating the object being finalized.

/// </param>

typedef void (CHAKRA_CALLBACK *JsFinalizeCallback)(_In_opt_ void *data);

/// <summary>

/// A function callback.

/// </summary>

/// <param name="callee">

/// A function object that represents the function being invoked.

/// </param>

/// <param name="isConstructCall">Indicates whether this is a regular call or a 'new' call.</param>

/// <param name="arguments">The arguments to the call.</param>

/// <param name="argumentCount">The number of arguments.</param>

/// <param name="callbackState">

/// The state passed to <c>JsCreateFunction</c>.

/// </param>

/// <returns>The result of the call, if any.</returns>

typedef _Ret_maybenull_ JsValueRef(CHAKRA_CALLBACK * JsNativeFunction)(_In_ JsValueRef callee, _In_ bool isConstructCall, _In_ JsValueRef *arguments, _In_ unsigned short argumentCount, _In_opt_ void *callbackState);

/// <summary>

/// A promise continuation callback.

/// </summary>

/// <remarks>

/// The host can specify a promise continuation callback in <c>JsSetPromiseContinuationCallback</c>. If

/// a script creates a task to be run later, then the promise continuation callback will be called with

/// the task and the task should be put in a FIFO queue, to be run when the current script is

/// done executing.

/// </remarks>

/// <param name="task">The task, represented as a JavaScript function.</param>

/// <param name="callbackState">The data argument to be passed to the callback.</param>

typedef void (CHAKRA_CALLBACK *JsPromiseContinuationCallback)(_In_ JsValueRef task, _In_opt_ void *callbackState);

/// <summary>

/// Creates a new runtime.

/// </summary>

/// <param name="attributes">The attributes of the runtime to be created.</param>

/// <param name="threadService">The thread service for the runtime. Can be null.</param>

/// <param name="runtime">The runtime created.</param>

/// <remarks>In the edge-mode binary, chakra.dll, this function lacks the <c>runtimeVersion</c>

/// parameter (compare to jsrt9.h).</remarks>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsCreateRuntime(

_In_ JsRuntimeAttributes attributes,

_In_opt_ JsThreadServiceCallback threadService,

_Out_ JsRuntimeHandle *runtime);

/// <summary>

/// Performs a full garbage collection.

/// </summary>

/// <param name="runtime">The runtime in which the garbage collection will be performed.</param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsCollectGarbage(

_In_ JsRuntimeHandle runtime);

/// <summary>

/// Disposes a runtime.

/// </summary>

/// <remarks>

/// Once a runtime has been disposed, all resources owned by it are invalid and cannot be used.

/// If the runtime is active (i.e. it is set to be current on a particular thread), it cannot

/// be disposed.

/// </remarks>

/// <param name="runtime">The runtime to dispose.</param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsDisposeRuntime(

_In_ JsRuntimeHandle runtime);

/// <summary>

/// Gets the current memory usage for a runtime.

/// </summary>

/// <remarks>

/// Memory usage can be always be retrieved, regardless of whether or not the runtime is active

/// on another thread.

/// </remarks>

/// <param name="runtime">The runtime whose memory usage is to be retrieved.</param>

/// <param name="memoryUsage">The runtime's current memory usage, in bytes.</param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsGetRuntimeMemoryUsage(

_In_ JsRuntimeHandle runtime,

_Out_ size_t *memoryUsage);

/// <summary>

/// Gets the current memory limit for a runtime.

/// </summary>

/// <remarks>

/// The memory limit of a runtime can be always be retrieved, regardless of whether or not the

/// runtime is active on another thread.

/// </remarks>

/// <param name="runtime">The runtime whose memory limit is to be retrieved.</param>

/// <param name="memoryLimit">

/// The runtime's current memory limit, in bytes, or -1 if no limit has been set.

/// </param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsGetRuntimeMemoryLimit(

_In_ JsRuntimeHandle runtime,

_Out_ size_t *memoryLimit);

/// <summary>

/// Sets the current memory limit for a runtime.

/// </summary>

/// <remarks>

/// <para>

/// A memory limit will cause any operation which exceeds the limit to fail with an "out of

/// memory" error. Setting a runtime's memory limit to -1 means that the runtime has no memory

/// limit. New runtimes default to having no memory limit. If the new memory limit exceeds

/// current usage, the call will succeed and any future allocations in this runtime will fail

/// until the runtime's memory usage drops below the limit.

/// </para>

/// <para>

/// A runtime's memory limit can be always be set, regardless of whether or not the runtime is

/// active on another thread.

/// </para>

/// </remarks>

/// <param name="runtime">The runtime whose memory limit is to be set.</param>

/// <param name="memoryLimit">

/// The new runtime memory limit, in bytes, or -1 for no memory limit.

/// </param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsSetRuntimeMemoryLimit(

_In_ JsRuntimeHandle runtime,

_In_ size_t memoryLimit);

/// <summary>

/// Sets a memory allocation callback for specified runtime

/// </summary>

/// <remarks>

/// <para>

/// Registering a memory allocation callback will cause the runtime to call back to the host

/// whenever it acquires memory from, or releases memory to, the OS. The callback routine is

/// called before the runtime memory manager allocates a block of memory. The allocation will

/// be rejected if the callback returns false. The runtime memory manager will also invoke the

/// callback routine after freeing a block of memory, as well as after allocation failures.

/// </para>

/// <para>

/// The callback is invoked on the current runtime execution thread, therefore execution is

/// blocked until the callback completes.

/// </para>

/// <para>

/// The return value of the callback is not stored; previously rejected allocations will not

/// prevent the runtime from invoking the callback again later for new memory allocations.

/// </para>

/// </remarks>

/// <param name="runtime">The runtime for which to register the allocation callback.</param>

/// <param name="callbackState">

/// User provided state that will be passed back to the callback.

/// </param>

/// <param name="allocationCallback">

/// Memory allocation callback to be called for memory allocation events.

/// </param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsSetRuntimeMemoryAllocationCallback(

_In_ JsRuntimeHandle runtime,

_In_opt_ void *callbackState,

_In_ JsMemoryAllocationCallback allocationCallback);

/// <summary>

/// Sets a callback function that is called by the runtime before garbage collection.

/// </summary>

/// <remarks>

/// <para>

/// The callback is invoked on the current runtime execution thread, therefore execution is

/// blocked until the callback completes.

/// </para>

/// <para>

/// The callback can be used by hosts to prepare for garbage collection. For example, by

/// releasing unnecessary references on Chakra objects.

/// </para>

/// </remarks>

/// <param name="runtime">The runtime for which to register the allocation callback.</param>

/// <param name="callbackState">

/// User provided state that will be passed back to the callback.

/// </param>

/// <param name="beforeCollectCallback">The callback function being set.</param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsSetRuntimeBeforeCollectCallback(

_In_ JsRuntimeHandle runtime,

_In_opt_ void *callbackState,

_In_ JsBeforeCollectCallback beforeCollectCallback);

/// <summary>

/// Adds a reference to a garbage collected object.

/// </summary>

/// <remarks>

/// This only needs to be called on <c>JsRef</c> handles that are not going to be stored

/// somewhere on the stack. Calling <c>JsAddRef</c> ensures that the object the <c>JsRef</c>

/// refers to will not be freed until <c>JsRelease</c> is called.

/// </remarks>

/// <param name="ref">The object to add a reference to.</param>

/// <param name="count">The object's new reference count (can pass in null).</param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsAddRef(

_In_ JsRef ref,

_Out_opt_ unsigned int *count);

/// <summary>

/// Releases a reference to a garbage collected object.

/// </summary>

/// <remarks>

/// Removes a reference to a <c>JsRef</c> handle that was created by <c>JsAddRef</c>.

/// </remarks>

/// <param name="ref">The object to remove the reference from.</param>

/// <param name="count">The object's new reference count (can pass in null).</param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsRelease(

_In_ JsRef ref,

_Out_opt_ unsigned int *count);

/// <summary>

/// Sets a callback function that is called by the runtime before garbage collection of

/// an object.

/// </summary>

/// <remarks>

/// <para>

/// The callback is invoked on the current runtime execution thread, therefore execution is

/// blocked until the callback completes.

/// </para>

/// </remarks>

/// <param name="ref">The object for which to register the callback.</param>

/// <param name="callbackState">

/// User provided state that will be passed back to the callback.

/// </param>

/// <param name="objectBeforeCollectCallback">The callback function being set. Use null to clear

/// previously registered callback.</param>

/// <returns>

/// The code <c>JsNoError</c> if the operation succeeded, a failure code otherwise.

/// </returns>

CHAKRA_API

JsSetObjectBeforeCollectCallback(

_In_ JsRef ref,

_In_opt_ void *callbackState,

_In_ JsObjectBeforeCollectCallback objectBeforeCollectCallback);

/// <summary>