mirror of
https://github.com/fluencelabs/gitbook-docs
synced 2025-05-09 06:32:16 +00:00
GitBook: [main] 56 pages modified
This commit is contained in:
boneyard93501
gitbook-bot
parent
fbb42a97fa
commit
f10cc106e7
10
SUMMARY.md
10
SUMMARY.md
@ -24,11 +24,13 @@
|
||||
* [Concepts](knowledge_knowledge/knowledge_concepts.md)
|
||||
* [Tools](knowledge_knowledge/knowledge_tools.md)
|
||||
* [Aquamarine](knowledge_knowledge/knowledge_aquamarine/README.md)
|
||||
* [AIR](knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md)
|
||||
* [Aqua](knowledge_knowledge/knowledge_aquamarine/hll.md)
|
||||
* [Aqua VM](knowledge_knowledge/knowledge_aquamarine/vm.md)
|
||||
* [Aqua](knowledge_knowledge/knowledge_aquamarine/hll/README.md)
|
||||
* [Aqua VM](knowledge_knowledge/knowledge_aquamarine/hll/vm.md)
|
||||
* [AIR](knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md)
|
||||
* [Marine](knowledge_knowledge/knowledge_aquamarine/marine/README.md)
|
||||
* [Marine-RS-SDK](knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md)
|
||||
* [Marine CLI](knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md)
|
||||
* [Marine Repl](knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md)
|
||||
* [Marine Rust SDK](knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md)
|
||||
* [Node](knowledge_knowledge/node/README.md)
|
||||
* [Overview](knowledge_knowledge/node/overview.md)
|
||||
* [Services](knowledge_knowledge/node/knowledge_node_services.md)
|
||||
|
||||
6
knowledge_knowledge/knowledge_aquamarine/hll/README.md
Normal file
6
knowledge_knowledge/knowledge_aquamarine/hll/README.md
Normal file
@ -0,0 +1,6 @@
|
||||
# Aqua
|
||||
|
||||
## Aquamarine High Level Language
|
||||
|
||||
_**Stay Tuned -- Coming Soon To A Repo Near You**_
|
||||
|
||||
@ -0,0 +1,55 @@
|
||||
# AIR
|
||||
|
||||
The Aquamarine Intermediate Representation \(AIR\) is a low level language to program both distributed networks and the services deployed on them. The language is comprised of a small number of instructions:
|
||||
|
||||
* _**call**_: : execution
|
||||
* _**seq**_ : sequential
|
||||
* _**par** :_ parallel
|
||||
* _**fold**_ : iteration
|
||||
* _**xor** :_ branching & error handling
|
||||
* _**null**_ : empty instruction
|
||||
|
||||
which operate on _peer-id_ \(location\), _service-id_, and _service method_ over an argument list, see Figure 1.
|
||||
|
||||
**Figure 1: AIR Instruction Definition** 
|
||||
|
||||
## Instructions
|
||||
|
||||
AIR instructions are intended to launch the execution of a service method as follows:
|
||||
|
||||
1. The method is executed on the peer specified by the peer id \(location\) parameter
|
||||
2. The peer is expected to have the Wasm service specified by the service id parameter
|
||||
3. The service must have a callable method specified be the method parameter
|
||||
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** 
|
||||
|
||||
The _**seq**_ instruction takes two instructions at most as its arguments and executes them sequentially, one after the other.
|
||||
|
||||
**Figure 3: Parallel Instruction** 
|
||||
|
||||
The _**par**_ instruction takes two instructions at most as its arguments and particles may execute on parallel paths iff each service referenced is hosted on a different node otherwise particles execute sequentially
|
||||
|
||||
TODO: add better graphic showing the disticntion of branching vs seq.
|
||||
|
||||
**Figure 4: Fold Instruction** 
|
||||
|
||||
The _**fold**_ instruction iterates over the elements of an array and workds as follows:
|
||||
|
||||
* _**fold**_ instruction takes three arguments: an array, a variable and an instruction
|
||||
* At each iteration, the variable is assigned an element of the array and the argument-instruction is executed
|
||||
* The argument-instruction can access the variable and uses the next statement to trigger the next iteration
|
||||
|
||||
Figure 5: Branching Instruction 
|
||||
|
||||
This instruction is intended for organizing branches in the flow of execution as well as for handling errors:
|
||||
|
||||
* The _**XOR**_ instruction takes two instructions as its arguments
|
||||
* The first instruction is executed and if the execution is successful, then the second instruction is ignored
|
||||
* If the first instruction fails, then the second one is executed.
|
||||
|
||||
**Figure 6: Null Instruction** 
|
||||
|
||||
This is an empty instruction: it takes no arguments and does nothing. The _**null**_ instruction is useful for generating code.
|
||||
|
||||
2
knowledge_knowledge/knowledge_aquamarine/hll/vm.md
Normal file
2
knowledge_knowledge/knowledge_aquamarine/hll/vm.md
Normal file
@ -0,0 +1,2 @@
|
||||
# Aqua VM
|
||||
|
||||
@ -0,0 +1,35 @@
|
||||
# Marine CLI
|
||||
|
||||
The [Marine command line tool](https://github.com/fluencelabs/marine) provides the project `marine build` functionality, analogous to `cargo build`, that results in the Rust code to be compiled to _wasm32-wasi_ modules. In addition, `marine` provides utilities to inspect Wasm modules, expose Wasm module attributes or manually set module properties.
|
||||
|
||||
```rust
|
||||
mbp16~(:|✔) % marine --help
|
||||
Fluence Marine command line tool 0.6.7
|
||||
Fluence Labs
|
||||
|
||||
USAGE:
|
||||
marine [SUBCOMMAND]
|
||||
|
||||
FLAGS:
|
||||
-h, --help Prints help information
|
||||
-V, --version Prints version information
|
||||
|
||||
SUBCOMMANDS:
|
||||
aqua Shows data types of provided module in a format suitable for Aqua
|
||||
build Builds provided Rust project to Wasm
|
||||
help Prints this message or the help of the given subcommand(s)
|
||||
info Shows manifest and sdk version of the provided Wasm file
|
||||
it Shows IT of the provided Wasm file
|
||||
repl Starts Fluence application service REPL
|
||||
set Sets interface types and version to the provided Wasm file
|
||||
mbp16~(:|✔) %
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -0,0 +1,35 @@
|
||||
# Marine Repl
|
||||
|
||||
[`mrepl`](https://crates.io/crates/mrepl) is a command line tool to locally run a Marine instance to inspect, run, and test Wasm modules and service configurations. We can run the Repl either with `mrepl` or `marine repl`
|
||||
|
||||
```text
|
||||
mbp16~(:|✔) % mrepl
|
||||
Welcome to the Marine REPL (version 0.7.2)
|
||||
Minimal supported versions
|
||||
sdk: 0.6.0
|
||||
interface-types: 0.20.0
|
||||
|
||||
New version is available! 0.7.2 -> 0.7.4
|
||||
To update run: cargo +nightly install mrepl --force
|
||||
|
||||
app service was created with service id = d81a4de5-55c3-4cb7-935c-3d5c6851320d
|
||||
elapsed time 486.234µs
|
||||
|
||||
1> help
|
||||
Commands:
|
||||
|
||||
n/new [config_path] create a new service (current will be removed)
|
||||
l/load <module_name> <module_path> load a new Wasm module
|
||||
u/unload <module_name> unload a Wasm module
|
||||
c/call <module_name> <func_name> [args] call function with given name from given module
|
||||
i/interface print public interface of all loaded modules
|
||||
e/envs <module_name> print environment variables of a module
|
||||
f/fs <module_name> print filesystem state of a module
|
||||
h/help print this message
|
||||
q/quit/Ctrl-C exit
|
||||
|
||||
2>
|
||||
```
|
||||
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Marine-RS-SDK
|
||||
# Marine Rust SDK
|
||||
|
||||
The marine-rs-sdk empowers developers to write services suitable for peer hosting in peer-to-peer networks using the Marine Virtual Machine by enabling the wasm32-wasi compile target for Marine. For an introduction to writing services with the marine-rs-sdk, see the [Developing Modules And Services](../../../development_development/) section.
|
||||
The [marine-rs-sdk](https://github.com/fluencelabs/marine-rs-sdk) empowers developers to write services suitable for peer hosting in peer-to-peer networks using the Marine Virtual Machine by enabling the wasm32-wasi compile target for Marine. For an introduction to writing services with the marine-rs-sdk, see the [Developing Modules And Services](../../../development_development/) section.
|
||||
|
||||
### API
|
||||
|
||||
@ -210,9 +210,10 @@ fn some_function() -> Data {
|
||||
> * wrap a structure with the `[marine]` macro
|
||||
> * all structure fields must be of the `ftype`
|
||||
> * the structure must be pointed to without preceding package import in a function signature, i.e`StructureName` but not `package_name::module_name::StructureName`
|
||||
> * wrapped structs can be imported from crates
|
||||
{% endhint %}
|
||||
|
||||
|
||||
####
|
||||
|
||||
#### Call Parameters
|
||||
|
||||
@ -325,6 +326,8 @@ pub struct MountedBinaryResult {
|
||||
|
||||
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.
|
||||
@ -375,7 +378,7 @@ The SDK has two useful features: `logger` and `debug`.
|
||||
|
||||
#### Logger
|
||||
|
||||
Using logging is a simple way to assist in the debugging without deploying the module\(s\) to a peer-to-peer network node. The `logger` feature allows you to use a special logger that is based at the top of the [log](https://crates.io/crates/log) crate.
|
||||
Using logging is a simple way to assist in debugging without deploying the module\(s\) to a peer-to-peer network node. The `logger` feature allows you to use a special logger that is based at the top of the [log](https://crates.io/crates/log) crate.
|
||||
|
||||
To enable logging please specify the `logger` feature of the Fluence SDK in `Config.toml` and add the [log](https://docs.rs/log/0.4.11/log/) crate:
|
||||
|
||||
@ -407,8 +410,6 @@ pub fn put(name: String, file_content: Vec<u8>) -> String {
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
In addition to the standard log creation features, the Fluence logger allows the so-called target map to be configured during the initialization step. This allows you to filter out logs by `logging_mask`, which can be set for each module in the service configuration. Let's consider an example:
|
||||
|
||||
```rust
|
||||
@ -431,15 +432,13 @@ pub fn main() {
|
||||
.unwrap();
|
||||
}
|
||||
|
||||
#[fce]
|
||||
#[marine]
|
||||
pub fn foo() {
|
||||
log::info!(target: "instruction", "this will print if (logging_mask & 1) != 0");
|
||||
log::info!(target: "data_cache", "this will print if (logging_mask & 2) != 0");
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
Here, an array called `TARGET_MAP` is defined and provided to a logger in the `main` function of a module. Each entry of this array contains a string \(a target\) and a number that represents the bit position in the 64-bit mask `logging_mask`. When you write a log message request `log::info!`, its target must coincide with one of the strings \(the targets\) defined in the `TARGET_MAP` array. The log will be printed if `logging_mask` for the module has the corresponding target bit set.
|
||||
|
||||
{% hint style="info" %}
|
||||
@ -477,7 +476,36 @@ The most important information these logs relates to the `allocate`/`deallocate`
|
||||
|
||||
|
||||
|
||||
|
||||
#### Module Manifest
|
||||
|
||||
The `module_manifest!` macro embeds the Interface Type \(IT\), SDK and Rust project version as well as additional project and build information into Wasm module. For the macro to be usable, it needs to be imported and initialized in the _main.rs_ file:
|
||||
|
||||
```text
|
||||
// main.rs
|
||||
use fluence::marine;
|
||||
use fluence::module_manifest; // import manifest macro
|
||||
|
||||
module_manifest!(); // initialize macro
|
||||
|
||||
fn main() {}
|
||||
|
||||
#[marine]
|
||||
fn some_function() {}
|
||||
}
|
||||
```
|
||||
|
||||
Using the Marine CLI, we can inspect a module's manifest with `marine info`:
|
||||
|
||||
```rust
|
||||
mbp16~/localdev/struct-exp(main|…) % marine info -i artifacts/*.wasm
|
||||
it version: 0.20.1
|
||||
sdk version: 0.6.0
|
||||
authors: The Fluence Team
|
||||
version: 0.1.0
|
||||
description: foo-wasm, a Marine wasi module
|
||||
repository:
|
||||
build time: 2021-06-11 21:08:59.855352 +00:00 UTC
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,14 +1,21 @@
|
||||
# Tools
|
||||
|
||||
## Fluence FCE REPL
|
||||
## Fluence Marine REPL
|
||||
|
||||
\`\`[`fce-repl`](https://crates.io/crates/frepl) is a command line tool \(CLI\) to locally inspect, run, and test module and service configurations making it an invaluable development tool.
|
||||
[`mrepl`](https://crates.io/crates/mrepl) is a command line tool \(CLI\) to locally run a Marine instance to inspect, run, and test module and service configurations.
|
||||
|
||||
```text
|
||||
mbp16~(:|✔) % fce-repl
|
||||
Welcome to the FCE REPL (version 0.5.2)
|
||||
app service was created with service id = 2321fc56-8cb9-497a-8abb-03d04665e1cc
|
||||
elapsed time 282.52µs
|
||||
mbp16~(:|✔) % mrepl
|
||||
Welcome to the Marine REPL (version 0.7.2)
|
||||
Minimal supported versions
|
||||
sdk: 0.6.0
|
||||
interface-types: 0.20.0
|
||||
|
||||
New version is available! 0.7.2 -> 0.7.4
|
||||
To update run: cargo +nightly install mrepl --force
|
||||
|
||||
app service was created with service id = d81a4de5-55c3-4cb7-935c-3d5c6851320d
|
||||
elapsed time 486.234µs
|
||||
|
||||
1> help
|
||||
Commands:
|
||||
@ -22,6 +29,8 @@ e/envs <module_name> print environment variables of a modul
|
||||
f/fs <module_name> print filesystem state of a module
|
||||
h/help print this message
|
||||
q/quit/Ctrl-C exit
|
||||
|
||||
2>
|
||||
```
|
||||
|
||||
## Fluence Proto Distributor: FLDIST
|
||||
|
||||
@ -43,7 +43,7 @@ Let's test the hex conversion test in isolation with the following AIR script:
|
||||
```
|
||||
|
||||
{% hint style="info" %}
|
||||
Aquamarine Intermediate Representation \(AIR\) is a low level implementation of Aquamarine to coordinate services into applications. For a detailed introduction to AIR, please refer to the [Knowledgebase](../knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md). For the remainder of this section, we will see three AIR _instructions_: _seq, xor,_ and _call._
|
||||
Aquamarine Intermediate Representation \(AIR\) is a low level implementation of Aquamarine to coordinate services into applications. For a detailed introduction to AIR, please refer to the [Knowledgebase](../knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md). For the remainder of this section, we will see three AIR _instructions_: _seq, xor,_ and _call._
|
||||
|
||||
_seq_ is the _sequential_ instruction that wraps arguments and executes them, you guessed it, sequentially. And yes, there is a _parallel_ instruction in the language.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user