From 0e966ac367e10ef03f8530693dc6934b84e370cb Mon Sep 17 00:00:00 2001 From: boneyard93501 Date: Fri, 11 Jun 2021 01:17:20 +0000 Subject: [PATCH] GitBook: [main] 54 pages modified --- .../knowledge_aquamarine/hll.md | 2 +- .../knowledge_aquamarine_air.md | 2 +- .../marine/marine-rs-sdk.md | 64 +++++++++++++++++++ .../knowledge_aquamarine/vm.md | 2 +- 4 files changed, 67 insertions(+), 3 deletions(-) diff --git a/knowledge_knowledge/knowledge_aquamarine/hll.md b/knowledge_knowledge/knowledge_aquamarine/hll.md index 630f2b9..6740663 100644 --- a/knowledge_knowledge/knowledge_aquamarine/hll.md +++ b/knowledge_knowledge/knowledge_aquamarine/hll.md @@ -1,4 +1,4 @@ -# Aqua +# HLL ## Aquamarine High Level Language diff --git a/knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md b/knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md index 25b942b..6dea06b 100644 --- a/knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md +++ b/knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md @@ -23,7 +23,7 @@ AIR instructions are intended to launch the execution of a service method as fol 4. The arguments specified by the argument list are passed to the method 5. The result of the method returned under the name output name -**Figure 2: Sequential Instruction** ![Execution](../../.gitbook/assets/air_sequential_2%20%281%29%20%281%29%20%281%29%20%281%29%20%281%29%20%282%29%20%283%29%20%284%29%20%282%29.png) +**Figure 2: Sequential Instruction** ![Execution](../../.gitbook/assets/air_sequential_2%20%281%29%20%281%29%20%281%29%20%281%29%20%281%29%20%282%29%20%283%29%20%282%29.png) The _**seq**_ instruction takes two instructions at most as its arguments and executes them sequentially, one after the other. diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md b/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md index 59d2e6e..1936bf1 100644 --- a/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md +++ b/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md @@ -162,6 +162,70 @@ Where +#### MountedBinaryResult + +Due to the inherent limitations of Wasm modules, such as a lack of sockets, it may be necessary for a module to interact with its host to bridge such gaps, e.g. use a https transport provider like _curl_. In order for a Wasm module to use a host's _curl_ capabilities, we need to provide access to the binary, which at the code level is achieved through the Rust `extern` block: + +```rust +// Importing a linked binary, curl, to a Wasm module +#![allow(improper_ctypes)] + +use fluence::marine; +use fluence::module_manifest; +use fluence::MountedBinaryResult; + +module_manifest!(); + +pub fn main() {} + +#[marine] +pub fn curl_request(curl_cmd: Vec) -> MountedBinaryResult { + let response = curl(curl_cmd); + response +} + +#[marine] +#[link(wasm_import_module = "host")] +extern "C" { + fn curl(cmd: Vec) -> MountedBinaryResult; +} +``` + +The above code creates a "curl adapter", i.e., a Wasm module that allows other Wasm modules to use the the `curl_request` function, which calls the imported _curl_ binary in this case, to make http calls. Please note that we are wrapping the `extern` block with the `[marine]`macro and introduce a Marine-native data structure [`MountedBinaryResult`](https://github.com/fluencelabs/marine/blob/master/examples/url-downloader/curl_adapter/src/main.rs) as the linked-function return value. + +Please not that if you want to use `curl_request` with testing, see below, the curl call needs to be marked unsafe, e.g.: + +```rust + let response = unsafe { curl(curl_cmd) }; +``` + +since cargo does not have access to the magic in place in the marine rs sdk to handle unsafe. + +MountedBinaryResult itself is a Marine-compatible struct containing a binary's return process code, error string, stdout and stderr: + +```rust +#[marine] +#[derive(Clone, PartialEq, Default, Eq, Debug, Serialize, Deserialize)] +pub struct MountedBinaryResult { + /// Return process exit code or host execution error code, where SUCCESS_CODE means success. + pub ret_code: i32, + + /// Contains the string representation of an error, if ret_code != SUCCESS_CODE. + pub error: String, + + /// The data that the process wrote to stdout. + pub stdout: Vec, + + /// The data that the process wrote to stderr. + pub stderr: Vec, +} + +``` + +MountedBinaryResult then can be used on a variety of match or conditional tests. + + + #### Testing Since we are compiling to a wasm32-wasi target with `ftype` constrains, the basic `cargo test` is not all that useful or even usable for our purposes. To alleviate that limitation, Fluence has introduced the [`[marine-test]` macro ](https://github.com/fluencelabs/marine-rs-sdk/tree/master/crates/marine-test-macro)that does a lot of the heavy lifting to allow developers to use `cargo test` as intended. That is, `[marine-test]` macro generates the necessary code to call Marine, one instance per test function, based on the Wasm module and associated configuration file so that the actual test function is run against the Wasm module not the native code. diff --git a/knowledge_knowledge/knowledge_aquamarine/vm.md b/knowledge_knowledge/knowledge_aquamarine/vm.md index ec6c770..aaded61 100644 --- a/knowledge_knowledge/knowledge_aquamarine/vm.md +++ b/knowledge_knowledge/knowledge_aquamarine/vm.md @@ -1,2 +1,2 @@ -# Aqua VM +# VM