From 1c063090c5f387f53885016a2044ba2479a0a2e8 Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Fri, 29 Mar 2019 16:22:38 +0100 Subject: [PATCH] doc(runtime-c-api) Add short module descriptions. --- lib/runtime-c-api/src/error.rs | 2 +- lib/runtime-c-api/src/export.rs | 3 +- lib/runtime-c-api/src/global.rs | 2 +- lib/runtime-c-api/src/import.rs | 3 +- lib/runtime-c-api/src/instance.rs | 2 +- lib/runtime-c-api/src/lib.rs | 83 +++++++++++++++++++++++++++++++ lib/runtime-c-api/src/memory.rs | 2 +- lib/runtime-c-api/src/module.rs | 2 +- lib/runtime-c-api/src/table.rs | 2 +- lib/runtime-c-api/src/value.rs | 2 +- 10 files changed, 94 insertions(+), 9 deletions(-) diff --git a/lib/runtime-c-api/src/error.rs b/lib/runtime-c-api/src/error.rs index 5980c79a9..c5f07a704 100644 --- a/lib/runtime-c-api/src/error.rs +++ b/lib/runtime-c-api/src/error.rs @@ -1,4 +1,4 @@ -//! Errors. +//! Read runtime errors. use libc::{c_char, c_int}; use std::cell::RefCell; diff --git a/lib/runtime-c-api/src/export.rs b/lib/runtime-c-api/src/export.rs index 6bcae32f2..7a7bbd47b 100644 --- a/lib/runtime-c-api/src/export.rs +++ b/lib/runtime-c-api/src/export.rs @@ -1,4 +1,5 @@ -//! Wasm exports. +//! Create, read, destroy export definitions (function, global, memory +//! and table) on an instance. use crate::{ error::{update_last_error, CApiError}, diff --git a/lib/runtime-c-api/src/global.rs b/lib/runtime-c-api/src/global.rs index 2e4ea645f..dc3910330 100644 --- a/lib/runtime-c-api/src/global.rs +++ b/lib/runtime-c-api/src/global.rs @@ -1,4 +1,4 @@ -//! Wasm global. +//! Create, set, get and destroy global variables of an instance. use crate::value::{wasmer_value_t, wasmer_value_tag}; use wasmer_runtime::Global; diff --git a/lib/runtime-c-api/src/import.rs b/lib/runtime-c-api/src/import.rs index cc3598078..a22b7f245 100644 --- a/lib/runtime-c-api/src/import.rs +++ b/lib/runtime-c-api/src/import.rs @@ -1,4 +1,5 @@ -//! Wasm imports. +//! Create, read, destroy import definitions (function, global, memory +//! and table) on an instance. use crate::{ error::{update_last_error, CApiError}, diff --git a/lib/runtime-c-api/src/instance.rs b/lib/runtime-c-api/src/instance.rs index a9d7d5555..87972060d 100644 --- a/lib/runtime-c-api/src/instance.rs +++ b/lib/runtime-c-api/src/instance.rs @@ -1,4 +1,4 @@ -//! Wasm instance. +//! Instantiate a module, call functions, and read exports. use crate::{ error::{update_last_error, CApiError}, diff --git a/lib/runtime-c-api/src/lib.rs b/lib/runtime-c-api/src/lib.rs index aa6455f60..eda9976d6 100644 --- a/lib/runtime-c-api/src/lib.rs +++ b/lib/runtime-c-api/src/lib.rs @@ -1,3 +1,86 @@ +//! # Wasmer Runtime C API +//! +//! Wasmer is a standalone JIT WebAssembly runtime, aiming to be fully +//! compatible with Emscripten, Rust and Go. [Learn +//! more](https://github.com/wasmerio/wasmer). +//! +//! This crate exposes a C and C++ API for the Wasmer runtime. +//! +//! # Usage +//! +//! The C and C++ header files can be found in the source tree of this +//! crate, respectively [`wasmer.h`][wasmer_h] and +//! [`wasmer.hh`][wasmer_hh]. They are automatically generated, and always +//! up-to-date in this repository. +//! +//! Here is a simple example to use the C API: +//! +//! ```c +//! #include +//! #include "wasmer.h" +//! #include +//! #include +//! +//! int main() +//! { +//! // Read the Wasm file bytes. +//! FILE *file = fopen("sum.wasm", "r"); +//! fseek(file, 0, SEEK_END); +//! long len = ftell(file); +//! uint8_t *bytes = malloc(len); +//! fseek(file, 0, SEEK_SET); +//! fread(bytes, 1, len, file); +//! fclose(file); +//! +//! // Prepare the imports. +//! wasmer_import_t imports[] = {}; +//! +//! // Instantiate! +//! wasmer_instance_t *instance = NULL; +//! wasmer_result_t instantiation_result = wasmer_instantiate(&instance, bytes, len, imports, 0); +//! +//! assert(instantiation_result == WASMER_OK); +//! +//! // Let's call a function. +//! // Start by preparing the arguments. +//! +//! // Value of argument #1 is `7i32`. +//! wasmer_value_t argument_one; +//! argument_one.tag = WASM_I32; +//! argument_one.value.I32 = 7; +//! +//! // Value of argument #2 is `8i32`. +//! wasmer_value_t argument_two; +//! argument_two.tag = WASM_I32; +//! argument_two.value.I32 = 8; +//! +//! // Prepare the arguments. +//! wasmer_value_t arguments[] = {argument_one, argument_two}; +//! +//! // Prepare the return value. +//! wasmer_value_t result_one; +//! wasmer_value_t results[] = {result_one}; +//! +//! // Call the `sum` function with the prepared arguments and the return value. +//! wasmer_result_t call_result = wasmer_instance_call(instance, "sum", arguments, 2, results, 1); +//! +//! // Let's display the result. +//! printf("Call result: %d\n", call_result); +//! printf("Result: %d\n", results[0].value.I32); +//! +//! // `sum(7, 8) == 15`. +//! assert(results[0].value.I32 == 15); +//! assert(call_result == WASMER_OK); +//! +//! wasmer_instance_destroy(instance); +//! +//! return 0; +//! } +//! ``` +//! +//! [wasmer_h]: ./wasmer.h +//! [wasmer_hh]: ./wasmer.hh + extern crate wasmer_runtime; extern crate wasmer_runtime_core; diff --git a/lib/runtime-c-api/src/memory.rs b/lib/runtime-c-api/src/memory.rs index f90965586..5927bee5e 100644 --- a/lib/runtime-c-api/src/memory.rs +++ b/lib/runtime-c-api/src/memory.rs @@ -1,4 +1,4 @@ -//! Wasm memory.o +//! Create, read, write, grow, destroy memory of an instance. use crate::{error::update_last_error, wasmer_limits_t, wasmer_result_t}; use libc::{uint32_t, uint8_t}; diff --git a/lib/runtime-c-api/src/module.rs b/lib/runtime-c-api/src/module.rs index 42d9815a6..62df2948f 100644 --- a/lib/runtime-c-api/src/module.rs +++ b/lib/runtime-c-api/src/module.rs @@ -1,4 +1,4 @@ -//! Wasm module. +//! Compile, validate, instantiate, serialize, and destroy modules. use crate::{ error::{update_last_error, CApiError}, diff --git a/lib/runtime-c-api/src/table.rs b/lib/runtime-c-api/src/table.rs index 84d3b794f..cd382912f 100644 --- a/lib/runtime-c-api/src/table.rs +++ b/lib/runtime-c-api/src/table.rs @@ -1,4 +1,4 @@ -//! Wasm tables. +//! Create, grow, destroy tables of an instance. use crate::{error::update_last_error, wasmer_limits_t, wasmer_result_t}; use libc::uint32_t; diff --git a/lib/runtime-c-api/src/value.rs b/lib/runtime-c-api/src/value.rs index c0a3e64d8..e5547bfa6 100644 --- a/lib/runtime-c-api/src/value.rs +++ b/lib/runtime-c-api/src/value.rs @@ -1,4 +1,4 @@ -//! Wasm values. +//! Create and map Rust to WebAssembly values. use libc::{int32_t, int64_t}; use wasmer_runtime::Value;