From 979a1c2b1dde6fd61c0566b398442c7898f40b1b Mon Sep 17 00:00:00 2001 From: Mirko Sertic Date: Mon, 10 Dec 2018 10:18:39 +0100 Subject: [PATCH] #77 Clarify project documentation --- README.md | 12 +++---- INTEROP.md => manual/INTEROP.md | 32 ++++++++++++++++++ IR.md => manual/IR.md | 4 +-- OPENCL.md => manual/OPENCL.md | 0 WASM.md => manual/WASM.md | 0 .../docassets}/ir_loopexample.svg | 0 .../docassets}/ir_loopexample_optimized.svg | 0 .../docassets}/jbox2ddemo.png | Bin 8 files changed, 40 insertions(+), 8 deletions(-) rename INTEROP.md => manual/INTEROP.md (70%) rename IR.md => manual/IR.md (85%) rename OPENCL.md => manual/OPENCL.md (100%) rename WASM.md => manual/WASM.md (100%) rename {docassets => manual/docassets}/ir_loopexample.svg (100%) rename {docassets => manual/docassets}/ir_loopexample_optimized.svg (100%) rename {docassets => manual/docassets}/jbox2ddemo.png (100%) diff --git a/README.md b/README.md index fb4fe2b386..b123c6cf6b 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Current travis-ci build status: [![Build Status](https://travis-ci.org/mirkosert ## Compiling strategies -The JVM Bytecode is parsed and transformed into an [intermediate representation](IR.md). This intermediate representation is passed thru +The JVM Bytecode is parsed and transformed into an [intermediate representation](manual/IR.md). This intermediate representation is passed thru optimizer stages and sent to a backend implementation for target code generation. The *JavaScript* backend transforms the intermediate representation into JavaScript. @@ -26,7 +26,7 @@ existing programs running on the JVM to utilize the vast power of modern GPUs. ## Demos -![Demo screenshot](docassets/jbox2ddemo.png) +![Demo screenshot](manual/docassets/jbox2ddemo.png) Demo | -------------------------------------------------| @@ -67,11 +67,11 @@ The interesting part is the `Kernel` class. At runtime, the JVM bytecode is tran heavily parallel on the GPU. Writing OpenCL Kernels in Java keeps developer productivity up and allows to write efficient algorithms that can transparently executed on the `GPU`. -Details about OpenCL and its usage with Bytecoder are documented [here](OPENCL.md). +Details about OpenCL and its usage with Bytecoder are documented [here](manual/OPENCL.md). ## Java to Target Platform Interop -Details about this are documented [here](INTEROP.md). +Details about this are documented [here](manual/INTEROP.md). ## Unit testing @@ -94,7 +94,7 @@ public class SimpleMathTest { } ``` -Is compiled to JavaScript and WebAssembly and executed using a Selenium Chrome driver. This test runner also supports comparison of original Java code and its cross compiled counterpart. This mechanism is the core tool to test the compiler and the Classlib. +is compiled to JavaScript and WebAssembly and executed using a Selenium Chrome driver. This test runner also supports comparison of original Java code and its cross compiled counterpart. This mechanism is the core tool to test the compiler and the Classlib. Bytecoder relies for WebAssembly unit testing on the WABT toolchain. Compilation is done by invoking the JS version of the WABT tools using Selenium and Chrome. To make everything working, you have to add `CHROMEDRIVER_BINARY` @@ -184,6 +184,6 @@ one implementation available. *JVM Bytecode* relies on the garbage collection mechanism provided by the Java Runtime. WebAssembly has currently no GC support in version 1.0. The WebAssembly backend must include garbage collection runtime code for memory management. The first implementation of such a GC will be a Mark-And-Sweep based. -Details about WebAssembly are documented [here](WASM.md) +Details about WebAssembly are documented [here](manual/WASM.md) The JavaScript backend relies on JavaScript garbage collection provided by the browser. diff --git a/INTEROP.md b/manual/INTEROP.md similarity index 70% rename from INTEROP.md rename to manual/INTEROP.md index 63eaa464d4..a34b3b555b 100644 --- a/INTEROP.md +++ b/manual/INTEROP.md @@ -4,6 +4,38 @@ Programs do now live on their own, they need to communicate with their environme This communication can be tricky if done on multiple environments. Bytecoder supports JavaScript, WebAssembly and OpenCL as target platforms. How does this wok? +## OpaqueReferenceTypes API + +Bytecoder allows transparent usage of APIs not implemented by Bytecoder itself. Such APIs are +provided by the host environment, for instance the DOM API or interaction with the browser window. +Bytecoder support such APIs by so called OpaqueReferenceTypes. For every external API, a new OpaqueRecerenceType +in form of a JVM interface class needs to be created. Bytecoder already comes with implementations for the +browser window and the DOM. + +See the following example, which demonstrates calls from Bytecoder to the HTML Canvas API: + +``` +Window window = Window.window(); +Document document = window.document(); +final HTMLCanvasElement theCanvas = document.getElementById("benchmark-canvas"); +CanvasRenderingContext2D renderingContext2D = theCanvas.getContext("2d"); + +renderingContext2D.moveTo(10, 10); +renderingContext2D.lineTo(20, 20); +``` + +Bytecoder also supports event listeners, as seen in the following example: + +``` +final HTMLElement button = document.getElementById("button"); +button.addEventListener("click", new Callback() { + @Override + public void run(ClickEvent aValue) { + button.style().setProperty("disabled", "true"); + } +}); +``` + ## Importing functionality from the host environment Using host environment functionality is quite common. This can be either simply diff --git a/IR.md b/manual/IR.md similarity index 85% rename from IR.md rename to manual/IR.md index fbf558a481..e42d006314 100644 --- a/IR.md +++ b/manual/IR.md @@ -1,7 +1,7 @@ # Intermediate representation The Bytecoder internal intermediate representation is basically a directed graph. The key idea behind this is described -[in this paper](core/src/main/java/de/mirkosertic/bytecoder/graph/c2-ir95-150110.pdf). +[in this paper](../core/src/main/java/de/mirkosertic/bytecoder/graph/c2-ir95-150110.pdf). Given this Java source code: @@ -28,7 +28,7 @@ The following graph shows the further optimized version of the previous loop: ![Intermediate representation graph optimized](docassets/ir_loopexample_optimized.svg) -Part of the compiler optimization is the [relooper step](core/src/main/java/de/mirkosertic/bytecoder/relooper/paper.pdf). +Part of the compiler optimization is the [relooper step](../core/src/main/java/de/mirkosertic/bytecoder/relooper/paper.pdf). Relooping tries to recover high level control flow constructs from the intermediate representation. This step eliminates the needs of GOTO statements and thus allows generation of more natural source code, which in turn can be easier read and optimized by Web Browsers or other tools. diff --git a/OPENCL.md b/manual/OPENCL.md similarity index 100% rename from OPENCL.md rename to manual/OPENCL.md diff --git a/WASM.md b/manual/WASM.md similarity index 100% rename from WASM.md rename to manual/WASM.md diff --git a/docassets/ir_loopexample.svg b/manual/docassets/ir_loopexample.svg similarity index 100% rename from docassets/ir_loopexample.svg rename to manual/docassets/ir_loopexample.svg diff --git a/docassets/ir_loopexample_optimized.svg b/manual/docassets/ir_loopexample_optimized.svg similarity index 100% rename from docassets/ir_loopexample_optimized.svg rename to manual/docassets/ir_loopexample_optimized.svg diff --git a/docassets/jbox2ddemo.png b/manual/docassets/jbox2ddemo.png similarity index 100% rename from docassets/jbox2ddemo.png rename to manual/docassets/jbox2ddemo.png