wasmer 0.4.0 → 0.5.0

data/README.md

@@ -1,332 +0,0 @@
-<p align="center">
-  <a href="https://wasmer.io" target="_blank" rel="noopener">
-    <img width="300" src="https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/logo.png" alt="Wasmer logo">
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://spectrum.chat/wasmer">
-    <img src="https://withspectrum.github.io/badge/badge.svg" alt="Join the Wasmer Community"></a>
-  <a href="https://rubygems.org/gems/wasmer">
-    <img src="https://img.shields.io/gem/v/wasmer.svg" alt="Gem"></a>
-  <a href="https://rubygems.org/gems/wasmer">
-    <img src="https://img.shields.io/gem/dt/wasmer.svg" alt="Number of gem downloads"></a>
-  <a href="https://github.com/wasmerio/wasmer/blob/master/LICENSE">
-    <img src="https://img.shields.io/github/license/wasmerio/wasmer.svg" alt="License"></a>
-</p>
-
-Wasmer is a Ruby library for executing WebAssembly binaries:
-
- * **Easy to use**: The `wasmer` API mimics the standard WebAssembly API,
- * **Fast**: `wasmer` executes the WebAssembly modules as fast as possible,
- * **Safe**: All calls to WebAssembly will be fast, but more
-   importantly, completely safe and sandboxed.
-
-# Install
-
-To install the `wasmer` Ruby gem, just run this command in your shell:
-
-```sh
-$ gem install wasmer
-```
-
-**Note**: [Rust][rust] is required to install the Ruby library (Cargo
-—the build tool for Rust— is used to compile the extension). See [how
-to install Rust][install-rust].
-
-[View the `wasmer` gem on RubyGems][wasmer-gem].
-
-[rust]: https://www.rust-lang.org/
-[install-rust]: https://www.rust-lang.org/tools/install
-[wasmer-gem]: https://rubygems.org/gems/wasmer
-
-# Example
-
-There is a toy program in `examples/simple.rs`, written in Rust (or
-any other language that compiles to Wasm):
-
-```rust
-#[no_mangle]
-pub extern fn sum(x: i32, y: i32) -> i32 {
-    x + y
-}
-```
-
-Once this program compiled to WebAssembly, we end up with a
-`examples/simple.wasm` binary file.
-
-Then, we can execute it in Ruby (!) with the `examples/simple.rb` file:
-
-```rb
-require "wasmer"
-
-bytes = IO.read "simple.wasm", mode: "rb"
-instance = Wasmer::Instance.new bytes
-puts instance.exports.sum 1, 2
-```
-
-And then, finally, enjoy by running:
-
-```sh
-$ ruby simple.rb
-3
-```
-
-# API documentation
-
-## The `Instance` class
-
-Instantiates a WebAssembly module represented by bytes, and calls
-exported functions on it:
-
-```ruby
-require "wasmer"
-
-# Get the Wasm module as bytes.
-wasm_bytes = IO.read "my_program.wasm", mode: "rb"
-
-# Instantiates the Wasm module.
-instance = Wasmer::Instance.new wasm_bytes
-
-# Call a function on it.
-result = instance.exports.sum 1, 2
-
-puts result # 3
-```
-
-### Exported functions
-
-All exported functions are accessible on the `exports`
-getter. Arguments of these functions are automatically casted to
-WebAssembly values.
-
-### Exported memory
-
-The `memory` getter exposes the `Memory` class representing the memory
-of that particular instance, e.g.:
-
-```ruby
-view = instance.memory.uint8_view
-```
-
-`Instance.memory` throws an exception if no memory is exported.
-
-See below for more information.
-
-### Exported globals
-
-The `globals` getter exposes the `ExportedGlobal` class represented an
-exported global variable, e.g.:
-
-```ruby
-# Get the `x` global.
-x = instance.globals.x
-
-# Check whether the global is mutable.
-assert x.mutable
-assert_equal x.value, 7
-
-# Update its value.
-x.value = 42
-
-# Tada!
-assert_equal x.value, 42
-```
-
-## The `Memory` class
-
-A WebAssembly instance has its own memory, represented by the `Memory`
-class. It is accessible by the `Wasmer::Instance.memory` getter.
-
-The `Memory.grow` methods allows to grow the memory by a number of
-pages (of 65kb each).
-
-```ruby
-instance.memory.grow 1
-```
-
-The `Memory` class offers methods to create views of the memory
-internal buffer, e.g. `uint8_view`, `int8_view`, `uint16_view`
-etc. All these methods accept one optional argument: `offset`, to
-subset the memory buffer at a particular offset. These methods return
-respectively a `*Array` object, i.e. `uint8_view` returns a
-`Uint8Array` object etc.
-
-```ruby
-offset = 7
-view = instance.memory.uint8_view offset
-
-puts view[0]
-```
-
-### The `*Array` classes
-
-These classes represent views over a memory buffer of an instance.
-
-| Class | View buffer as a sequence of… | Bytes per element |
-|-|-|-|
-| `Int8Array` | `int8` | 1 |
-| `Uint8Array` | `uint8` | 1 |
-| `Int16Array` | `int16` | 2 |
-| `Uint16Array` | `uint16` | 2 |
-| `Int32Array` | `int32` | 4 |
-| `Uint32Array` | `uint32` | 4 |
-
-All these classes share the same implementation. Taking the example of
-`Uint8Array`, the class looks like this:
-
-```ruby
-class Uint8Array
-    def bytes_per_element
-    def length
-    def [](index)
-    def []=(index, value)
-end
-```
-
-Let's see it in action:
-
-```ruby
-require "wasmer"
-
-# Get the Wasm module as bytes.
-wasm_bytes = IO.read "my_program.wasm", mode: "rb"
-
-# Instantiates the Wasm module.
-instance = Wasmer::Instance.new wasm_bytes
-
-# Call a function that returns a pointer to a string for instance.
-pointer = instance.exports.return_string
-
-# Get the memory view, with the offset set to `pointer` (default is 0).
-memory = instance.memory.uint8_view pointer
-
-# Read the string pointed by the pointer.
-
-string = ""
-
-memory.each do |char|
-  break if char == 0
-  string += char.chr
-end
-
-puts string # Hello, World!
-```
-
-Notice that `*Array` treat bytes in little-endian, as required by the
-WebAssembly specification, [Chapter Structure, Section Instructions,
-Sub-Section Memory
-Instructions](https://webassembly.github.io/spec/core/syntax/instructions.html#memory-instructions):
-
-> All values are read and written in [little
-> endian](https://en.wikipedia.org/wiki/Endianness#Little-endian) byte
-> order.
-
-Each view shares the same memory buffer internally. Let's have some fun:
-
-```ruby
-int8 = instance.memory.int8_view
-int16 = instance.memory.int16_view
-int32 = instance.memory.int32_view
-
-               b₁
-            ┌┬┬┬┬┬┬┐
-int8[0] = 0b00000001
-               b₂
-            ┌┬┬┬┬┬┬┐
-int8[1] = 0b00000100
-               b₃
-            ┌┬┬┬┬┬┬┐
-int8[2] = 0b00010000
-               b₄
-            ┌┬┬┬┬┬┬┐
-int8[3] = 0b01000000
-
-// No surprise with the following assertions.
-                  b₁
-               ┌┬┬┬┬┬┬┐
-assert_equal 0b00000001, int8[0]
-                  b₂
-               ┌┬┬┬┬┬┬┐
-assert_equal 0b00000100, int8[1]
-                  b₃
-               ┌┬┬┬┬┬┬┐
-assert_equal 0b00010000, int8[2]
-                  b₄
-               ┌┬┬┬┬┬┬┐
-assert_equal 0b01000000, int8[3]
-
-// The `int16` view reads 2 bytes.
-                  b₂       b₁
-               ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐
-assert_equal 0b00000100_00000001, int16[0]
-                  b₄       b₃
-               ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐
-assert_equal 0b01000000_00010000, int16[1]
-
-// The `int32` view reads 4 bytes.
-                  b₄       b₃       b₂       b₁
-               ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐ ┌┬┬┬┬┬┬┐
-assert_equal 0b01000000_00010000_00000100_00000001, int32[0]
-```
-
-## The `Module` class
-
-The `Module` class contains one static method `validate`, that checks
-whether the given bytes represent valid WebAssembly bytes:
-
-```ruby
-require "wasmer"
-
-wasm_bytes = IO.read "my_program.wasm", mode: "rb"
-
-if not Wasmer::Module.validate wasm_bytes
-    puts "The program seems corrupted."
-end
-```
-
-This function returns a boolean.
-
-# Install and Testing
-
-To compile the entire project, run the following commands:
-
-```sh
-$ just build
-$ just test
-$ ruby examples/simple.rb
-```
-
-(Yes, you need [`just`][just]).
-
-[just]: https://github.com/casey/just/
-
-# What is WebAssembly?
-
-Quoting [the WebAssembly site][wasm]:
-
-> WebAssembly (abbreviated Wasm) is a binary instruction format for a
-> stack-based virtual machine. Wasm is designed as a portable target
-> for compilation of high-level languages like C/C++/Rust, enabling
-> deployment on the web for client and server applications.
-
-About speed:
-
-> WebAssembly aims to execute at native speed by taking advantage of
-> [common hardware
-> capabilities](https://webassembly.org/docs/portability/#assumptions-for-efficient-execution)
-> available on a wide range of platforms.
-
-About safety:
-
-> WebAssembly describes a memory-safe, sandboxed [execution
-> environment](https://webassembly.org/docs/semantics/#linear-memory) […].
-
-[wasm]: https://webassembly.org/
-
-# License
-
-The entire project is under the MIT License. Please read [the
-`LICENSE` file][license].
-
-[license]: https://github.com/wasmerio/wasmer/blob/master/LICENSE

data/lib/wasmer/version.rb

@@ -1,3 +0,0 @@
-module Wasmer
-  VERSION = "0.4.0"
-end

data/src/error.rs

@@ -1,16 +0,0 @@
-//! Functions to handle error or exception correctly.
-
-use rutie::{AnyException, VM};
-
-pub fn unwrap_or_raise<Output, Function>(f: Function) -> Output
-where
-    Function: FnOnce() -> Result<Output, AnyException>,
-{
-    match f() {
-        Ok(x) => x,
-        Err(e) => {
-            VM::raise_ex(e);
-            unreachable!()
-        }
-    }
-}

data/src/instance/exports.rs

@@ -1,215 +0,0 @@
-//! The `ExportedFunctions` WebAssembly class.
-
-use crate::error::unwrap_or_raise;
-use lazy_static::lazy_static;
-use rutie::{
-    class, methods,
-    rubysys::{class, value::ValueType},
-    types::{Argc, Value},
-    util::str_to_cstring,
-    wrappable_struct, AnyException, AnyObject, Array, Boolean, Exception, Fixnum, Float, NilClass,
-    Object, Symbol,
-};
-use std::rc::Rc;
-use wasmer_runtime::{self as runtime, types::Type};
-
-/// The `ExportedFunctions` Ruby class.
-pub struct ExportedFunctions {
-    /// The WebAssembly runtime.
-    instance: Rc<runtime::Instance>,
-}
-
-impl ExportedFunctions {
-    /// Create a new instance of the `ExportedFunctions` Ruby class.
-    pub fn new(instance: Rc<runtime::Instance>) -> Self {
-        Self { instance }
-    }
-
-    /// Check that an exported function exists.
-    pub fn respond_to_missing(&self, method_name: &str) -> bool {
-        self.instance.dyn_func(method_name).is_ok()
-    }
-
-    /// Call an exported function on the given WebAssembly instance.
-    pub fn method_missing(
-        &self,
-        method_name: &str,
-        arguments: Array,
-    ) -> Result<AnyObject, AnyException> {
-        let function = self.instance.dyn_func(method_name).map_err(|_| {
-            AnyException::new(
-                "RuntimeError",
-                Some(&format!("Function `{}` does not exist.", method_name)),
-            )
-        })?;
-        let signature = function.signature();
-        let parameters = signature.params();
-        let number_of_parameters = parameters.len() as isize;
-        let number_of_arguments = arguments.length() as isize;
-        let diff: isize = number_of_parameters - number_of_arguments;
-
-        if diff > 0 {
-            return Err(AnyException::new(
-                "ArgumentError",
-                Some(&format!(
-                    "Missing {} argument(s) when calling `{}`: Expect {} argument(s), given {}.",
-                    diff, method_name, number_of_parameters, number_of_arguments
-                )),
-            ));
-        } else if diff < 0 {
-            return Err(AnyException::new(
-                "ArgumentError",
-                Some(&format!(
-                    "Given {} extra argument(s) when calling `{}`: Expect {} argument(s), given {}.",
-                    diff.abs(), method_name, number_of_parameters, number_of_arguments
-                )),
-            ));
-        }
-
-        let mut function_arguments =
-            Vec::<runtime::Value>::with_capacity(number_of_parameters as usize);
-
-        for (nth, (parameter, argument)) in parameters.iter().zip(arguments.into_iter()).enumerate()
-        {
-            let value = match (parameter, argument.ty()) {
-                (Type::I32, ValueType::Fixnum) => runtime::Value::I32(
-                    argument
-                        .try_convert_to::<Fixnum>()
-                        .map_err(|_| {
-                            AnyException::new(
-                                "TypeError",
-                                Some(&format!(
-                                    "Cannot convert argument #{} to a WebAssembly i32 value.",
-                                    nth + 1
-                                )),
-                            )
-                        })?
-                        .to_i32(),
-                ),
-                (Type::I64, ValueType::Fixnum) => runtime::Value::I64(
-                    argument
-                        .try_convert_to::<Fixnum>()
-                        .map_err(|_| {
-                            AnyException::new(
-                                "TypeError",
-                                Some(&format!(
-                                    "Cannot convert argument #{} to a WebAssembly i64 value.",
-                                    nth + 1
-                                )),
-                            )
-                        })?
-                        .to_i64(),
-                ),
-                (Type::F32, ValueType::Float) => runtime::Value::F32(
-                    argument
-                        .try_convert_to::<Float>()
-                        .map_err(|_| {
-                            AnyException::new(
-                                "TypeError",
-                                Some(&format!(
-                                    "Cannot convert argument #{} to a WebAssembly f32 value.",
-                                    nth + 1
-                                )),
-                            )
-                        })?
-                        .to_f64() as f32,
-                ),
-                (Type::F64, ValueType::Float) => runtime::Value::F64(
-                    argument
-                        .try_convert_to::<Float>()
-                        .map_err(|_| {
-                            AnyException::new(
-                                "TypeError",
-                                Some(&format!(
-                                    "Cannot convert argument #{} to a WebAssembly f64 value.",
-                                    nth + 1
-                                )),
-                            )
-                        })?
-                        .to_f64(),
-                ),
-                (_, ty) => {
-                    return Err(AnyException::new(
-                        "ArgumentError",
-                        Some(&format!(
-                            "Cannot convert argument #{} to a WebAssembly value. Only integers and floats are supported. Given `{:?}`.",
-                            nth + 1,
-                            ty
-                        ))));
-                }
-            };
-
-            function_arguments.push(value);
-        }
-
-        let results = function
-            .call(function_arguments.as_slice())
-            .map_err(|e| AnyException::new("RuntimeError", Some(&format!("{}", e))))?;
-
-        if !results.is_empty() {
-            Ok(match results[0] {
-                runtime::Value::I32(result) => Fixnum::new(result as i64).into(),
-                runtime::Value::I64(result) => Fixnum::new(result).into(),
-                runtime::Value::F32(result) => Float::new(result as f64).into(),
-                runtime::Value::F64(result) => Float::new(result).into(),
-                runtime::Value::V128(_result) => {
-                    return Err(AnyException::new(
-                        "RuntimeError",
-                        Some("Type `V128` isn't supported yet."),
-                    ))
-                }
-            })
-        } else {
-            Ok(NilClass::new().into())
-        }
-    }
-}
-
-wrappable_struct!(
-    ExportedFunctions,
-    ExportedFunctionsWrapper,
-    EXPORTED_FUNCTIONS_WRAPPER
-);
-
-class!(RubyExportedFunctions);
-
-#[rustfmt::skip]
-methods!(
-    RubyExportedFunctions,
-    itself,
-
-    // Glue code to call the `ExportedFunctions.respond_to` method.
-    fn ruby_exported_functions_method_exists(symbol: Symbol, _include_private: Boolean) -> Boolean {
-        unwrap_or_raise(|| {
-            let symbol = symbol?;
-            let exported_functions = itself.get_data(&*EXPORTED_FUNCTIONS_WRAPPER);
-
-            Ok(Boolean::new(exported_functions.respond_to_missing(symbol.to_str())))
-        })
-    }
-);
-
-/// Glue code to call the `ExportedFunctions.method_missing` method.
-pub extern "C" fn ruby_exported_functions_method_missing(
-    argc: Argc,
-    argv: *const AnyObject,
-    itself: RubyExportedFunctions,
-) -> AnyObject {
-    unwrap_or_raise(|| {
-        let arguments = Value::from(0);
-
-        unsafe {
-            let argv_pointer = argv as *const Value;
-
-            class::rb_scan_args(argc, argv_pointer, str_to_cstring("*").as_ptr(), &arguments)
-        };
-
-        let mut arguments = Array::from(arguments);
-        let method_name = unsafe { arguments.shift().to::<Symbol>() };
-        let method_name = method_name.to_str();
-
-        itself
-            .get_data(&*EXPORTED_FUNCTIONS_WRAPPER)
-            .method_missing(method_name, arguments)
-    })
-}