Difference between revisions of "WebAssembly/DOM"

From Lazarus wiki
Jump to navigationJump to search
(16 intermediate revisions by 2 users not shown)
Line 26: Line 26:
 
* double
 
* double
 
* nil
 
* nil
* string (utf8)
+
* string (utf8 converted to utf16)
 
* unicodestring
 
* unicodestring
 
* widestring
 
* widestring
* PChar - using strlen to get the size
+
* PChar - using strlen to get the size and utf8 converted to utf16
 +
* PWideChar - using strlen to get the size
 
* TJSObject and IJSObject - its ObjectID is passed to the JS side, where the corresponding JS object is used
 
* TJSObject and IJSObject - its ObjectID is passed to the JS side, where the corresponding JS object is used
 
* JSUndefined
 
* JSUndefined
 +
* TJOB_JSValue
 +
 +
=== Function Result ===
 +
 +
Calling a JS function is done via the ''InvokeJS*Result'' functions, e.g. ''aJSDate.InvokeJSUnicodeStringResult('toLocaleDateString',[])'' which returns a ''UnicodeString''.
 +
 +
If the function does not exist, an ''EJSInvoke'' exception is raised.
 +
 +
If the function returns the JS undefined value, JOB returns the default value, e.g. InvokeJSUnicodeStringResult returns the empty string, InvokeJSDoubleResult returns NaN, InvokeJSObjectResult returns nil, InvokeJSBooleanResult returns false.
 +
 +
If the function returns an incompatible type, e.g. InvokeJSUnicodeStringResult returns a number, an ''EJSInvoke'' exception is raised.
 +
 +
To retrieve any kind of JS value, use InvokeJSValueResult.
  
 
=== Callbacks ===
 
=== Callbacks ===
  
An event handler in WebAssembly must be callable from Javascript.  
+
An event handler in WebAssembly can be called from Javascript.  
The '''AddEventListener''' has a single method signature, so a single exported function from webassembly can be used for this:  
+
 
 +
At the moment only methods (of object) are supported.
 +
 
 +
Every function type needs a callback, which decodes the arguments and encode the result.
 +
 
 +
For example TJSEventHandler:
  
all that is needed is to pass the object pointer & method pointer (both integers), plus the ID of the event object.
+
<source lang="pascal">
Pointers to methods & instances can be passed between JS and webassembly, this can be used.
+
type
Alternatively: Using the FPC dispatchstr mechanism, the correct method can be called in Webassembly. To be checked.
+
  TJSEventHandler = function(Event: IJSEventListenerEvent): boolean of object;
 +
...
 +
function JOBCallTJSEventHandler(const aMethod: TMethod; Args: PByte): PByte;
 +
var
 +
  h: TJOBCallbackHelper;
 +
  Event: IJSEventListenerEvent;
 +
begin
 +
  h.Init(Args);
 +
  // get first argument as IJSEventListenerEvent
 +
  Event:=h.GetObject(TJSEventListenerEvent) as IJSEventListenerEvent;
 +
  // call the method and encode the result
 +
  Result:=h.AllocBool(TJSEventHandler(aMethod)(Event));
 +
end;
 +
</source>
  
Advantage of this method is that only a couple of webassembly and Javascript exports are needed.
+
TJOBCallbackHelper provides functions to decode arguments and encode the result.
 +
 
 +
Passing a method as argument works like this:
 +
 
 +
<source lang="pascal">
 +
type
 +
  IJSEventTarget = interface
 +
    ['{1883145B-C826-47D1-9C63-47546BA536BD}']
 +
    procedure addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
 +
  end;
 +
 
 +
  TJSEventTarget = class(TJSObject,IJSEventTarget)
 +
    procedure addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
 +
  end;
 +
...
 +
procedure TJSEventTarget.addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
 +
var
 +
  m: TJOB_JSValueMethod;
 +
begin
 +
  // combine the users method and the callback into one argument m
 +
  m:=TJOB_JSValueMethod.Create(TMethod(aListener),@JOBCallTJSEventHandler);
 +
  try
 +
    // call the JS function addEventListener(aName,m)
 +
    InvokeJSNoResult('addEventListener',[aName,m]);
 +
  finally
 +
    m.Free;
 +
  end;
 +
end;
 +
</source>
 +
 
 +
=== Type casts ===
 +
 
 +
Often a low level interface needs to be type casted to a descendant (or another type). For example ''JSDocument.getElementById'' returns a IJSElement, which is type casted to IJSHTMLElement:
 +
 
 +
<source lang="pascal">
 +
var
 +
  Elem: IJSElement;
 +
  HTMLElem: IJSHTMLElement;
 +
begin
 +
  Elem := JSDocument.getElementById('button');
 +
  // type casting to IJSHTMLElement require creating a special TJSHTMLElement:
 +
  HTMLElem := TJSHTMLElement.Cast(Elem) as IJSHTMLElement;
 +
end;
 +
</source>
 +
 
 +
This special TJSHTMLElement has the same ObjectId, but it does not own it. It merely keeps an interface reference to the original IJSObject. When all interface references are released, the JS object is released,
 +
 
 +
=== Typeof ===
 +
 
 +
'''InvokeJSTypeOf'''
 +
 
 +
See the JOBResult_* constants in unit JOB_Shared.
  
 
== Implementation details ==
 
== Implementation details ==
Line 69: Line 152:
 
     destructor Destroy; override;
 
     destructor Destroy; override;
 
     property ObjectID: TJOBObjectID read FObjectID;
 
     property ObjectID: TJOBObjectID read FObjectID;
 +
    // call a function
 
     procedure InvokeJSNoResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeSetType = jisCall); virtual;
 
     procedure InvokeJSNoResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeSetType = jisCall); virtual;
 
     function InvokeJSBooleanResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeGetType = jigCall): Boolean; virtual;
 
     function InvokeJSBooleanResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeGetType = jigCall): Boolean; virtual;
Line 77: Line 161:
 
     function InvokeJSUtf8StringResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeGetType = jigCall): String; virtual;
 
     function InvokeJSUtf8StringResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeGetType = jigCall): String; virtual;
 
     function InvokeJSLongIntResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeGetType = jigCall): LongInt; virtual;
 
     function InvokeJSLongIntResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeGetType = jigCall): LongInt; virtual;
 +
    // read a property
 
     function ReadJSPropertyBoolean(const aName: string): boolean; virtual;
 
     function ReadJSPropertyBoolean(const aName: string): boolean; virtual;
 
     function ReadJSPropertyDouble(const aName: string): double; virtual;
 
     function ReadJSPropertyDouble(const aName: string): double; virtual;
Line 84: Line 169:
 
     function ReadJSPropertyLongInt(const aName: string): LongInt; virtual;
 
     function ReadJSPropertyLongInt(const aName: string): LongInt; virtual;
 
     function ReadJSPropertyValue(const aName: string): TJOB_JSValue; virtual;
 
     function ReadJSPropertyValue(const aName: string): TJOB_JSValue; virtual;
 +
    // write a property
 
     procedure WriteJSPropertyBoolean(const aName: string; Value: Boolean); virtual;
 
     procedure WriteJSPropertyBoolean(const aName: string; Value: Boolean); virtual;
 
     procedure WriteJSPropertyDouble(const aName: string; Value: Double); virtual;
 
     procedure WriteJSPropertyDouble(const aName: string; Value: Double); virtual;
Line 90: Line 176:
 
     procedure WriteJSPropertyObject(const aName: string; Value: TJSObject); virtual;
 
     procedure WriteJSPropertyObject(const aName: string; Value: TJSObject); virtual;
 
     procedure WriteJSPropertyLongInt(const aName: string; Value: LongInt); virtual;
 
     procedure WriteJSPropertyLongInt(const aName: string; Value: LongInt); virtual;
 +
    // create a new object using the new-operator
 +
    function NewJSObject(Const Args: Array of const; aResultClass: TJSObjectClass): TJSObject; virtual;
 
   end;
 
   end;
 
</source>
 
</source>
Line 104: Line 192:
 
The result is checked for the requested type and then returned to the wasm.
 
The result is checked for the requested type and then returned to the wasm.
  
If the result is an object, an ID is generated (simple counter), the result value is stored in an array FLocalObjects.  
+
If the result is an object, an ID is generated (simple counter), the result value is stored in an array '''FLocalObjects'''.  
  
The ID is returned to the webassembly, which will use the ID to create a TJSObject descendent.
+
The ID is returned to the webassembly, which will use the ID to create a ''TJSObject'' descendent.
  
The destructor of '''TJSObject''' calls a '''release_object''' function in javascript if the '''ObjectID''' is positive. The '''release_object''' function simply sets '''FLocalObjects['id']''' to
+
The destructor of '''TJSObject''' calls a '''__job_release_object''' function in javascript if the '''ObjectID''' is positive. The '''ReleaseObject''' function simply sets '''FLocalObjects[id]''' to
null. (so the browser also releases it)
+
null, so the browser also releases it.
  
 
The above is a basic invoke mechanism for Javascript code.
 
The above is a basic invoke mechanism for Javascript code.
Line 146: Line 234:
  
 
* read/write array elements
 
* read/write array elements
* new operator
+
* store/cache callbacks to support removeEventListener
 +
* extend webidl2pas to produce code for wasm-job
 +
 
 +
[[Category:WebAssembly]]

Revision as of 09:02, 2 June 2022

Accessing JS Objects from WebAssembly

JS Object Bridge - JOB

General architecture

Create pascal units, containing ‘proxy’ classes: calling a method on a proxy class will call the corresponding class in JS. The proxy classes can be generated by adapting the existing webidl2pas tool.

Data transfer between JS/WebAssembly

JS/Webassembly interface only supports passing atomic types like boolean, integers and floats, not objects or strings.

Solution:

  • Every object is stored in an array with ID: TJOBObjectID
  • ID is used to pass references to object between JS and Webassembly
  • Lifetime is controlled from WebAssembly.
  • By using interfaces, the lifetime of objects can be controlled by the compiler.
  • Methods can be called using an invoke mechanism.
  • Due to limited type support in Javascript, only a handful of types must be supported by invoke.

Function Arguments

When calling a JS function from wasm, you can pass the following types/constants:

  • boolean
  • integers (limited to double, because all numbers in JS are double, so up to 54 bits)
  • double
  • nil
  • string (utf8 converted to utf16)
  • unicodestring
  • widestring
  • PChar - using strlen to get the size and utf8 converted to utf16
  • PWideChar - using strlen to get the size
  • TJSObject and IJSObject - its ObjectID is passed to the JS side, where the corresponding JS object is used
  • JSUndefined
  • TJOB_JSValue

Function Result

Calling a JS function is done via the InvokeJS*Result functions, e.g. aJSDate.InvokeJSUnicodeStringResult('toLocaleDateString',[]) which returns a UnicodeString.

If the function does not exist, an EJSInvoke exception is raised.

If the function returns the JS undefined value, JOB returns the default value, e.g. InvokeJSUnicodeStringResult returns the empty string, InvokeJSDoubleResult returns NaN, InvokeJSObjectResult returns nil, InvokeJSBooleanResult returns false.

If the function returns an incompatible type, e.g. InvokeJSUnicodeStringResult returns a number, an EJSInvoke exception is raised.

To retrieve any kind of JS value, use InvokeJSValueResult.

Callbacks

An event handler in WebAssembly can be called from Javascript.

At the moment only methods (of object) are supported.

Every function type needs a callback, which decodes the arguments and encode the result.

For example TJSEventHandler:

type
  TJSEventHandler = function(Event: IJSEventListenerEvent): boolean of object;
...
function JOBCallTJSEventHandler(const aMethod: TMethod; Args: PByte): PByte;
var
  h: TJOBCallbackHelper;
  Event: IJSEventListenerEvent;
begin
  h.Init(Args);
  // get first argument as IJSEventListenerEvent
  Event:=h.GetObject(TJSEventListenerEvent) as IJSEventListenerEvent;
  // call the method and encode the result
  Result:=h.AllocBool(TJSEventHandler(aMethod)(Event));
end;

TJOBCallbackHelper provides functions to decode arguments and encode the result.

Passing a method as argument works like this:

type
  IJSEventTarget = interface
    ['{1883145B-C826-47D1-9C63-47546BA536BD}']
    procedure addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
  end;

  TJSEventTarget = class(TJSObject,IJSEventTarget)
    procedure addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
  end;
...
procedure TJSEventTarget.addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
var
  m: TJOB_JSValueMethod;
begin
  // combine the users method and the callback into one argument m
  m:=TJOB_JSValueMethod.Create(TMethod(aListener),@JOBCallTJSEventHandler);
  try
    // call the JS function addEventListener(aName,m)
    InvokeJSNoResult('addEventListener',[aName,m]);
  finally
    m.Free;
  end;
end;

Type casts

Often a low level interface needs to be type casted to a descendant (or another type). For example JSDocument.getElementById returns a IJSElement, which is type casted to IJSHTMLElement:

var 
  Elem: IJSElement;
  HTMLElem: IJSHTMLElement;
begin
  Elem := JSDocument.getElementById('button');
  // type casting to IJSHTMLElement require creating a special TJSHTMLElement:
  HTMLElem := TJSHTMLElement.Cast(Elem) as IJSHTMLElement;
end;

This special TJSHTMLElement has the same ObjectId, but it does not own it. It merely keeps an interface reference to the original IJSObject. When all interface references are released, the JS object is released,

Typeof

InvokeJSTypeOf

See the JOBResult_* constants in unit JOB_Shared.

Implementation details

Here are some technical notes describing the various architectural decisions.

A tool is created to generate an interface from the .webidl files. These files for example exist in the mozilla firefox repo on github: WebIDL

IJSElement = interface(IJSObject)
  ['someawfulGUID']
  function childElementCount : Integer;
  function firstElementChild : IJSElement;
  // all other
end;

In implementation, the following kind of code can be found:

// Hand crafted in e.g. JSObject unit
  TJSObject = class(TInterfacedObject,IJSObject)
  public
    constructor CreateFromID(aID: TJOBObjectID); virtual;
    destructor Destroy; override;
    property ObjectID: TJOBObjectID read FObjectID;
    // call a function
    procedure InvokeJSNoResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeSetType = jisCall); virtual;
    function InvokeJSBooleanResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeGetType = jigCall): Boolean; virtual;
    function InvokeJSDoubleResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeGetType = jigCall): Double; virtual;
    function InvokeJSUnicodeStringResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeGetType = jigCall): UnicodeString; virtual;
    function InvokeJSObjectResult(const aName: string; Const Args: Array of const; aResultClass: TJSObjectClass; Invoke: TJOBInvokeGetType = jigCall): TJSObject; virtual;
    function InvokeJSValueResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeGetType = jigCall): TJOB_JSValue; virtual;
    function InvokeJSUtf8StringResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeGetType = jigCall): String; virtual;
    function InvokeJSLongIntResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeGetType = jigCall): LongInt; virtual;
    // read a property
    function ReadJSPropertyBoolean(const aName: string): boolean; virtual;
    function ReadJSPropertyDouble(const aName: string): double; virtual;
    function ReadJSPropertyUnicodeString(const aName: string): UnicodeString; virtual;
    function ReadJSPropertyObject(const aName: string; aResultClass: TJSObjectClass): TJSObject; virtual;
    function ReadJSPropertyUtf8String(const aName: string): string; virtual;
    function ReadJSPropertyLongInt(const aName: string): LongInt; virtual;
    function ReadJSPropertyValue(const aName: string): TJOB_JSValue; virtual;
    // write a property
    procedure WriteJSPropertyBoolean(const aName: string; Value: Boolean); virtual;
    procedure WriteJSPropertyDouble(const aName: string; Value: Double); virtual;
    procedure WriteJSPropertyUnicodeString(const aName: string; const Value: UnicodeString); virtual;
    procedure WriteJSPropertyUtf8String(const aName: string; const Value: String); virtual;
    procedure WriteJSPropertyObject(const aName: string; Value: TJSObject); virtual;
    procedure WriteJSPropertyLongInt(const aName: string; Value: LongInt); virtual;
    // create a new object using the new-operator
    function NewJSObject(Const Args: Array of const; aResultClass: TJSObjectClass): TJSObject; virtual;
  end;

The various Invoke* functions encode the arguments in a memory block so they can be read on the JS side, then calls a Invoke_*Result function which lives in Javascript, and which is imported from the browser.

That function does the actual call: it uses ObjectID to look for the Self object in an array:

  • Negative IDs are special: window, document.
  • positive IDs are temporary objects created via the InvokeJSObjectResult, see below.

The Invoke_*Result pas2js function decodes the arguments and uses TJSFunction.apply to execute the requested function. The result is checked for the requested type and then returned to the wasm.

If the result is an object, an ID is generated (simple counter), the result value is stored in an array FLocalObjects.

The ID is returned to the webassembly, which will use the ID to create a TJSObject descendent.

The destructor of TJSObject calls a __job_release_object function in javascript if the ObjectID is positive. The ReleaseObject function simply sets FLocalObjects[id] to null, so the browser also releases it.

The above is a basic invoke mechanism for Javascript code.

This basic mechanism is then used by a modified version of the webidl program to generate proxy definitions. For each object in Javascript, 2 definitions are generated:

  • The interface (see above for an example)
  • An implementation object as below, descendant of TJSObject
// Generated from webIDL in jsweb/jsdom unit.
 
IJSElement = interface(IJSNode)
  function childElementCount : Integer;
  function firstElementChild : IJSElement;
end;

TJSElementImpl = class(TJSObject,IJSElement)
  function childElementCount : Integer;
  function firstElementChild : IJSElement;
  // all other
end;
 
function TJSElementImpl.childElementCount : Integer;
begin
  Result:=ReadJSPropertyLongInt('childElementCount');
end;
 
function TJSElementImpl.firstElementChild : IJSElement;
begin
  Result:=ReadJSPropertyObject('firstElementChild',TJSElementImpl) as IJSElement;
end;

ToDos

  • read/write array elements
  • store/cache callbacks to support removeEventListener
  • extend webidl2pas to produce code for wasm-job