Difference between revisions of "WebAssembly/DOM"

From Lazarus wiki
Jump to navigationJump to search
Line 35: Line 35:
  
 
<source lang="pascal">
 
<source lang="pascal">
IElement = interface ['someawfulGUID'] (IJSObject);
+
IJSElement = interface(IJSObject)
 +
  ['someawfulGUID']
 
   function childElementCount : Integer;
 
   function childElementCount : Integer;
   function firstElementChild : IElement;
+
   function firstElementChild : IJSElement;
 
   // all other
 
   // all other
 
end;
 
end;
 
</source>
 
</source>
 
Only the interfaces are exposed in the API to access the DOM.
 
  
 
In implementation, the following kind of code can be found:
 
In implementation, the following kind of code can be found:
Line 48: Line 47:
 
<source lang="pascal">
 
<source lang="pascal">
 
// Hand crafted in e.g. JSObject unit
 
// Hand crafted in e.g. JSObject unit
TJSObject = class(TInterfacedObject)
+
  TJSObject = class(TInterfacedObject,IJSObject)
private
+
   public
   FObjectID: NativeInt;
 
public
 
 
     constructor CreateFromID(aID: TJOBObjectID); virtual;
 
     constructor CreateFromID(aID: TJOBObjectID); virtual;
 
     destructor Destroy; override;
 
     destructor Destroy; override;
Line 76: Line 73:
 
     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;
end;
+
  end;
 
</source>
 
</source>
  
The various '''Invoke*''' functions encode the arguments in a memory block so they can be read on the JS side, then calls a JSInvokeNNN function which lives in
+
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.  
 
Javascript, and which is imported from the browser.  
  
Line 85: Line 82:
  
 
* Negative IDs are special: window, document.
 
* Negative IDs are special: window, document.
* positive IDs are temporary objects created via the InvokeJSObjectResult, see below.
+
* positive IDs are temporary objects created via the '''InvokeJSObjectResult''', see below.
  
The '''Invoke*''' function decodes the arguments and uses '''TJSFunction.apply''' to execute the requested function.
+
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.
 
The result is checked for the requested type and then returned to the wasm.
  
Line 118: Line 115:
 
end;
 
end;
 
   
 
   
function TElementImpl.childElementCount : Integer;
+
function TJSElementImpl.childElementCount : Integer;
 
begin
 
begin
 
   Result:=ReadJSPropertyLongInt('childElementCount');
 
   Result:=ReadJSPropertyLongInt('childElementCount');
 
end;
 
end;
 
   
 
   
function TElementImpl.firstElementChild : IElement;
+
function TJSElementImpl.firstElementChild : IJSElement;
 
begin
 
begin
   Result:=ReadJSPropertyObject('firstElementChild',TElementImpl) as IElement;
+
   Result:=ReadJSPropertyObject('firstElementChild',TJSElementImpl) as IJSElement;
 
end;
 
end;
 
</source>
 
</source>

Revision as of 00:45, 27 May 2022

Accessing JS Objects from WebAssembly

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.

Callbacks

An event handler in WebAssembly must be callable from Javascript. The AddEventListener has a single method signature, so a single exported function from webassembly can be used for this:

all that is needed is to pass the object pointer & method pointer (both integers), plus the ID of the event object. Pointers to methods & instances can be passed between JS and webassembly, this can be used. Alternatively: Using the FPC dispatchstr mechanism, the correct method can be called in Webassembly. To be checked.

Advantage of this method is that only a couple of webassembly and Javascript exports are needed.

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;
    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;
    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;
    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;
  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 release_object function in javascript if the ObjectID is positive. The release_object 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;