mirror of
https://github.com/fluencelabs/aqua-book
synced 2024-12-04 15:20:19 +00:00
GitBook: [bb-edit] 31 pages and one asset modified
This commit is contained in:
boneyard93501
gitbook-bot
parent
d54b086ab4
commit
d6c3316ef4
BIN
.gitbook/assets/screen-shot-2021-06-29-at-1.06.39-pm.png
Normal file
BIN
.gitbook/assets/screen-shot-2021-06-29-at-1.06.39-pm.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 982 KiB |
@ -4,9 +4,9 @@ While Execution flow organizes the flow from peer to peer, Abilities & Services
|
||||
|
||||
Ability is a concept of "what is possible in this context": like a peer-specific trait or a typeclass. It will be better explained once abilities passing is implemented.
|
||||
|
||||
{% embed url="https://github.com/fluencelabs/aqua/issues/33" %}
|
||||
{% embed url="https://github.com/fluencelabs/aqua/issues/33" caption="" %}
|
||||
|
||||
### Services
|
||||
## Services
|
||||
|
||||
A Service interfaces functions \(often WASM ones\) executable on a peer. Example of service definition:
|
||||
|
||||
@ -19,7 +19,7 @@ service MyService:
|
||||
|
||||
Service functions in Aqua have no function body. Computations, of any complexity, are implemented with any programming language that fits, and then brought to the Aqua execution context. Aqua calls these functions but does not peak into what's going on inside.
|
||||
|
||||
#### Built-in services
|
||||
### Built-in services
|
||||
|
||||
Some services may be singletons available on all peers. Such services are called built-ins, and are always available in any scope.
|
||||
|
||||
@ -27,41 +27,41 @@ Some services may be singletons available on all peers. Such services are called
|
||||
-- Built-in service has a constant ID, so it's always resolved
|
||||
service Op("op"):
|
||||
noop()
|
||||
|
||||
|
||||
func foo():
|
||||
-- Call the noop function of "op" service locally
|
||||
Op.noop()
|
||||
Op.noop()
|
||||
```
|
||||
|
||||
#### Service resolution
|
||||
### Service resolution
|
||||
|
||||
A peer may host many services of the same type. To distinguish services from each other, Aqua requires Service resolution to be done: that means, the developer must provide an ID of the service to be used on the peer.
|
||||
|
||||
```text
|
||||
service MyService:
|
||||
noop()
|
||||
|
||||
|
||||
func foo():
|
||||
-- Will fail
|
||||
MyService.noop()
|
||||
|
||||
|
||||
-- Resolve MyService: it has id "noop"
|
||||
MyService "noop"
|
||||
|
||||
|
||||
-- Can use it now
|
||||
MyService.noop()
|
||||
|
||||
|
||||
on "other peer":
|
||||
-- Should fail: we haven't resolved MyService ID on other peer
|
||||
MyService.noop()
|
||||
|
||||
|
||||
-- Resolve MyService on peer "other peer"
|
||||
MyService "other noop"
|
||||
MyService.noop()
|
||||
|
||||
|
||||
-- Moved back to initial peer, here MyService is resolved to "noop"
|
||||
MyService.noop()
|
||||
```
|
||||
|
||||
There's no way to call an external function in Aqua without defining all the data types and the service type. One of the most convinient ways to do it is to generate Aqua types from WASM code in Marine \[link to Marine docs\].
|
||||
There's no way to call an external function in Aqua without defining all the data types and the service type. One of the most convinient ways to do it is to generate Aqua types from WASM code in Marine \[link to Marine docs\].
|
||||
|
||||
|
||||
@ -9,17 +9,17 @@ func foo(): -- Comments are allowed almost everywhere
|
||||
bar(5)
|
||||
```
|
||||
|
||||
Values in Aqua have types, which are designated by a colon, `:`, as seen in function signature below. The type of a return, which is yielded when a function is executed, is denoted by an arrow pointing to the right `->` , whereas yielding is denoted by an arrow pointing to the left `<-`.
|
||||
Values in Aqua have types, which are designated by a colon, `:`, as seen in function signature below. The type of a return, which is yielded when a function is executed, is denoted by an arrow pointing to the right `->` , whereas yielding is denoted by an arrow pointing to the left `<-`.
|
||||
|
||||
```text
|
||||
-- Define a function that yields a string
|
||||
func bar(arg: i16) -> string:
|
||||
-- Call a function
|
||||
smth(arg)
|
||||
|
||||
|
||||
-- Yield a value from a function
|
||||
x <- smth(arg)
|
||||
|
||||
|
||||
-- Return a yielded results from a function
|
||||
<- "return literal"
|
||||
```
|
||||
@ -52,5 +52,3 @@ Reference:
|
||||
|
||||
* [Expressions](expressions/)
|
||||
|
||||
|
||||
|
||||
|
||||
@ -20,23 +20,23 @@ Stream is a kind of [collection](types.md#collection-types), and can be used whe
|
||||
func foo(peer: string, relay: ?string):
|
||||
on peer via relay:
|
||||
Op.noop()
|
||||
|
||||
|
||||
-- Dirty hack for lack of type variance, and lack of cofunctors
|
||||
service OpStr("op"):
|
||||
identity: string -> string
|
||||
|
||||
|
||||
func bar(peer: string, relay: string):
|
||||
relayMaybe: *string
|
||||
if peer != %init_peer_id%:
|
||||
-- To write into a stream, function call is required
|
||||
relayMaybe <- OpStr.identity(relay)
|
||||
-- Pass a stream as an optional value
|
||||
foo(peer, relayMaybe)
|
||||
foo(peer, relayMaybe)
|
||||
```
|
||||
|
||||
But the most powerful uses of streams come along with parallelism, which incurs non-determinism.
|
||||
|
||||
### Streams lifecycle and guarantees
|
||||
## Streams lifecycle and guarantees
|
||||
|
||||
Streams lifecycle can be divided into three stages:
|
||||
|
||||
@ -49,26 +49,25 @@ Consider the following example:
|
||||
```text
|
||||
func foo(peers: []string) -> string:
|
||||
resp: *string
|
||||
|
||||
|
||||
-- Will go to all peers in parallel
|
||||
for p <- peers par:
|
||||
on p:
|
||||
-- Do something
|
||||
resp <- Srv.call()
|
||||
|
||||
|
||||
resp2: *string
|
||||
|
||||
|
||||
-- What is resp at this point?
|
||||
for r <- resp par:
|
||||
on r:
|
||||
resp2 <- Srv.call()
|
||||
|
||||
|
||||
-- Wait for 6 responses
|
||||
Op.identity(resp2!5)
|
||||
-- Once we have 5 responses, merge them
|
||||
r <- Srv.concat(resp2)
|
||||
<- r
|
||||
|
||||
```
|
||||
|
||||
In this case, for each peer in peers, something is going to be written into resp stream.
|
||||
@ -81,5 +80,5 @@ And then the results are sent to the first peer, to call Op.identity there. This
|
||||
|
||||
When it is, stream as a whole is consumed to produce a scalar value, which is returned.
|
||||
|
||||
During execution, involved peers have different views on the state of execution: parallel branches of for have no access to each other's data. Finally, execution flows to the initial peer. Initial peer merges writes to the resp stream, and merges writes to the resp2 stream. It's done in conflict-free fashion. More than that, head of resp, resp2 streams will not change from each peer's point of view: it's immutable, and new values are only appended. However, different peers may have different order of the stream values, depending on the order of receiving these values.
|
||||
During execution, involved peers have different views on the state of execution: parallel branches of for have no access to each other's data. Finally, execution flows to the initial peer. Initial peer merges writes to the resp stream, and merges writes to the resp2 stream. It's done in conflict-free fashion. More than that, head of resp, resp2 streams will not change from each peer's point of view: it's immutable, and new values are only appended. However, different peers may have different order of the stream values, depending on the order of receiving these values.
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
Aqua supports branching: you can return one value or another, recover from the error, or check a boolean expression.
|
||||
|
||||
### Contract
|
||||
## Contract
|
||||
|
||||
The second arm of the conditional operator is executed iff the first arm failed.
|
||||
|
||||
@ -12,9 +12,9 @@ A conditional block is considered executed iff any arm was executed successfully
|
||||
|
||||
A conditional block is considered failed iff the second \(recovery\) arm fails to execute.
|
||||
|
||||
### Conditional operations
|
||||
## Conditional operations
|
||||
|
||||
#### try
|
||||
### try
|
||||
|
||||
Tries to perform operations, or swallows the error \(if there's no catch, otherwise after the try block\).
|
||||
|
||||
@ -27,7 +27,7 @@ try:
|
||||
x <- foo()
|
||||
```
|
||||
|
||||
#### catch
|
||||
### catch
|
||||
|
||||
Catches the standard error from `try` block.
|
||||
|
||||
@ -47,7 +47,7 @@ data LastError:
|
||||
peer_id: string -- On what peer the error happened
|
||||
```
|
||||
|
||||
#### if
|
||||
### if
|
||||
|
||||
If corresponds to `match`, `mismatch` extension of π-calculus.
|
||||
|
||||
@ -56,21 +56,21 @@ x = true
|
||||
if x:
|
||||
-- always executed
|
||||
foo()
|
||||
|
||||
|
||||
if x == false:
|
||||
-- never executed
|
||||
bar()
|
||||
|
||||
|
||||
if x != false:
|
||||
-- executed
|
||||
baz()
|
||||
baz()
|
||||
```
|
||||
|
||||
Currently, you may only use one `==`, `!=` operator in the `if` expression, or compare with true.
|
||||
|
||||
Both operands can be variables.
|
||||
|
||||
#### else
|
||||
### else
|
||||
|
||||
Just the second branch of `if`, in case the condition does not hold.
|
||||
|
||||
@ -78,12 +78,12 @@ Just the second branch of `if`, in case the condition does not hold.
|
||||
if true:
|
||||
foo()
|
||||
else:
|
||||
bar()
|
||||
bar()
|
||||
```
|
||||
|
||||
If you want to set a variable based on condition, see Conditional return.
|
||||
|
||||
#### otherwise
|
||||
### otherwise
|
||||
|
||||
You may add `otherwise` to provide recovery for any block or expression:
|
||||
|
||||
@ -94,7 +94,7 @@ otherwise:
|
||||
y <- bar()
|
||||
```
|
||||
|
||||
### Conditional return
|
||||
## Conditional return
|
||||
|
||||
In Aqua, functions may have only one return expression, which is very last. And conditional expressions cannot define the same variable:
|
||||
|
||||
@ -102,7 +102,7 @@ In Aqua, functions may have only one return expression, which is very last. And
|
||||
try:
|
||||
x <- foo()
|
||||
otherwise:
|
||||
x <- bar() -- Error: name x was already defined in scope, can't compile
|
||||
x <- bar() -- Error: name x was already defined in scope, can't compile
|
||||
```
|
||||
|
||||
So to get the value based on condition, we need to use a [writeable collection](../types.md#collection-types).
|
||||
@ -114,7 +114,7 @@ try:
|
||||
resultBox <- foo()
|
||||
otherwise:
|
||||
resultBox <- bar()
|
||||
|
||||
|
||||
-- now result contains only one value, let's extract it!
|
||||
result = resultBox!
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
In Aqua, two operations corresponds to it: you can call a service function \(it's just available when it's needed\), and you can use `for` loop to iterate on collections.
|
||||
|
||||
### For expression
|
||||
## For expression
|
||||
|
||||
In short, `for` looks like the following:
|
||||
|
||||
@ -13,13 +13,13 @@ xs: []string
|
||||
|
||||
for x <- xs:
|
||||
y <- foo(x)
|
||||
|
||||
|
||||
-- x and y are not accessible there, you can even redefine them
|
||||
x <- bar()
|
||||
y <- baz()
|
||||
y <- baz()
|
||||
```
|
||||
|
||||
### Contract
|
||||
## Contract
|
||||
|
||||
Iterations of `for` loop are executed sequentially by default.
|
||||
|
||||
@ -29,7 +29,7 @@ For loop's code has access to all variables above.
|
||||
|
||||
For can be executed on a variable of any [Collection type](../types.md#collection-types).
|
||||
|
||||
### Conditional for
|
||||
## Conditional for
|
||||
|
||||
You can make several trials in a loop, and break once any trial succeeded.
|
||||
|
||||
@ -43,7 +43,7 @@ for x <- xs try:
|
||||
|
||||
Contract is changed as in [Parallel](parallel.md#contract) flow.
|
||||
|
||||
### Parallel for
|
||||
## Parallel for
|
||||
|
||||
Running many operations in parallel is the most commonly used pattern for `for`.
|
||||
|
||||
@ -53,16 +53,16 @@ xs: []string
|
||||
for x <- xs par:
|
||||
on x:
|
||||
foo()
|
||||
|
||||
|
||||
-- Once the fastest x succeeds, execution continues
|
||||
-- If you want to make the subsequent execution independent from for,
|
||||
-- mark it with par, e.g.:
|
||||
par continueWithBaz()
|
||||
par continueWithBaz()
|
||||
```
|
||||
|
||||
Contract is changed as in [Conditional](conditional.md#contract) flow.
|
||||
|
||||
### Export data from for
|
||||
## Export data from for
|
||||
|
||||
The way to export data from `for` is the same as in [Conditional return](conditional.md#conditional-return) and [Race patterns](parallel.md#join-behavior).
|
||||
|
||||
@ -74,12 +74,12 @@ return: *string
|
||||
for x <- xs par:
|
||||
on x:
|
||||
return <- foo()
|
||||
|
||||
|
||||
-- Wait for 6 fastest results -- see Join behavior
|
||||
baz(return!5, return)
|
||||
baz(return!5, return)
|
||||
```
|
||||
|
||||
### For on streams
|
||||
## For on streams
|
||||
|
||||
For on streams is one of the most complex and powerful parts of Aqua. See [CRDT streams](../crdt-streams.md) for details.
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
Parallel execution is where everything becomes shiny.
|
||||
|
||||
### Contract
|
||||
## Contract
|
||||
|
||||
Parallel arms have no access to each other's data. Sync points must be explicit \(see Join behavior\).
|
||||
|
||||
@ -10,7 +10,7 @@ If any arm is executed successfully, the flow execution continues.
|
||||
|
||||
All the data defined in parallel arms is available in the subsequent code.
|
||||
|
||||
### Implementation limitation
|
||||
## Implementation limitation
|
||||
|
||||
Parallel execution has some implementation limitations:
|
||||
|
||||
@ -20,9 +20,9 @@ Parallel execution has some implementation limitations:
|
||||
|
||||
We might overcome these limitations later, but for now, plan your application design having this in mind.
|
||||
|
||||
### Parallel operations
|
||||
## Parallel operations
|
||||
|
||||
### par
|
||||
## par
|
||||
|
||||
`par` syntax is derived from π-calculus notation of parallelism: `A | B`
|
||||
|
||||
@ -39,7 +39,7 @@ on "peer 1":
|
||||
x <- foo()
|
||||
par on "peer 2":
|
||||
y <- bar()
|
||||
|
||||
|
||||
-- Once any of the previous functions return x or y,
|
||||
-- execution continues. We don't know the order, so
|
||||
-- if y is returned first, hello(x) will not execute
|
||||
@ -54,7 +54,7 @@ par hello(y)
|
||||
|
||||
`par` works in infix manner between the previously stated function and the next one.
|
||||
|
||||
#### co
|
||||
### co
|
||||
|
||||
`co` , short for `coroutine`, prefixes an operation to send it to background. From π-calculus perspective, it's the same as `A | null`, where `null`-process is the one that does nothing and completes instantly.
|
||||
|
||||
@ -65,7 +65,7 @@ co foo()
|
||||
-- Do something on another peer, not blocking the flow on this one
|
||||
co on "some peer":
|
||||
baz()
|
||||
|
||||
|
||||
-- This foo does not wait for baz()
|
||||
foo()
|
||||
|
||||
@ -80,7 +80,7 @@ bar()
|
||||
bax(x)
|
||||
```
|
||||
|
||||
### Join behavior
|
||||
## Join behavior
|
||||
|
||||
Join means that data was created by different parallel execution flows and then used on a single peer to perform computations. It works the same way for any parallel blocks, be it `par`, `co` or something else \(`for par`\).
|
||||
|
||||
@ -91,16 +91,16 @@ In Aqua, you can refer to previously defined variables. In case of sequential co
|
||||
on peer1:
|
||||
-- Go to peer1, execute foo, remember x
|
||||
x <- foo()
|
||||
|
||||
|
||||
-- x is available at this point
|
||||
|
||||
|
||||
on peer2:
|
||||
-- Go to peer2, execute bar, remember y
|
||||
y <- bar()
|
||||
|
||||
-- Both x and y are available at this point
|
||||
-- Use them in a function
|
||||
baz(x, y)
|
||||
baz(x, y)
|
||||
```
|
||||
|
||||
Let's make this script parallel: execute `foo` and `bar` on different peers in parallel, then use both to compute `baz`.
|
||||
@ -110,9 +110,9 @@ Let's make this script parallel: execute `foo` and `bar` on different peers in p
|
||||
on peer1:
|
||||
-- Go to peer1, execute foo, remember x
|
||||
x <- foo()
|
||||
|
||||
|
||||
-- Notice par on the next line: it means, go to peer2 in parallel with peer1
|
||||
|
||||
|
||||
par on peer2:
|
||||
-- Go to peer2, execute bar, remember y
|
||||
y <- bar()
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
By default, Aqua code is executed line by line, sequentially.
|
||||
|
||||
### Contract
|
||||
## Contract
|
||||
|
||||
Data from the first arm is available in the second branch.
|
||||
|
||||
@ -12,9 +12,9 @@ If any arm failed, then the whole sequence is failed.
|
||||
|
||||
If all arms executed successfully, then the whole sequence is executed successfully.
|
||||
|
||||
### Sequential operations
|
||||
## Sequential operations
|
||||
|
||||
#### call arrow
|
||||
### call arrow
|
||||
|
||||
Any runnable piece of code in Aqua is an arrow from its domain to codomain.
|
||||
|
||||
@ -34,7 +34,7 @@ z <- Op.identity(y)
|
||||
|
||||
When you write `<-`, this means not just "assign results of the function on the right to variable on the left". It means that all the effects are executed: [service](../abilities-and-services.md) may change state, [topology](../topology.md) may be shifted. But you end up being \(semantically\) on the same peer where you have called the arrow.
|
||||
|
||||
#### on
|
||||
### on
|
||||
|
||||
`on` denotes the peer where the code must be executed. `on` is handled sequentially, and the code inside is executed line by line by default.
|
||||
|
||||
@ -42,19 +42,19 @@ When you write `<-`, this means not just "assign results of the function on the
|
||||
func foo():
|
||||
-- Will be executed where `foo` was executed
|
||||
bar()
|
||||
|
||||
|
||||
-- Move to another peer
|
||||
on another_peer:
|
||||
-- To call bar, we need to leave the peer where we were and get to another_peer
|
||||
-- It's done automagically
|
||||
bar()
|
||||
|
||||
|
||||
on third_peer via relay:
|
||||
-- This is executed on third_peer
|
||||
-- But we denote that to get to third_peer and to leave third_peer
|
||||
-- an additional hop is needed: get to relay, then to peer
|
||||
bar()
|
||||
|
||||
|
||||
-- Will be executed in the `foo` call site again
|
||||
-- To get from the previous `bar`, compiler will add a hop to relay
|
||||
bar()
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
Aqua source file has head and body. The body contains function definitions, services, types, constants. Header manages what is imported from other files, and what is exported from this one.
|
||||
|
||||
### Import expression
|
||||
## Import expression
|
||||
|
||||
The main way to import a file is via `import` expression:
|
||||
|
||||
@ -17,11 +17,9 @@ Aqua compiler takes a source directory and a list of import directories \(usuall
|
||||
|
||||
Everything defined in the file is imported into the current namespace.
|
||||
|
||||
### `Use` expression
|
||||
## `Use` expression
|
||||
|
||||
Use expression makes it possible to import a subset of a file, or to alias the imports to avoid collisions.
|
||||
|
||||
{% embed url="https://github.com/fluencelabs/aqua/issues/30" %}
|
||||
|
||||
|
||||
{% embed url="https://github.com/fluencelabs/aqua/issues/30" caption="" %}
|
||||
|
||||
|
||||
@ -4,12 +4,11 @@ description: Define where the code is to be executed and how to get there
|
||||
|
||||
# Topology
|
||||
|
||||
Aqua lets developers to describe the whole distributed workflow in a single script, link data, recover from errors, implement complex patterns like backpressure, and more. Hence, topology is at the heart of Aqua.
|
||||
|
||||
Aqua lets developers to describe the whole distributed workflow in a single script, link data, recover from errors, implement complex patterns like backpressure, and more. Hence, topology is at the heart of Aqua.
|
||||
Topology in Aqua is declarative: You just need to say where a piece of code must be executed, on what peer, and optionally how to get there. he Aqua compiler will add all the required network hops.
|
||||
|
||||
Topology in Aqua is declarative: You just need to say where a piece of code must be executed, on what peer, and optionally how to get there. he Aqua compiler will add all the required network hops.
|
||||
|
||||
### On expression
|
||||
## On expression
|
||||
|
||||
`on` expression moves execution to the specified peer:
|
||||
|
||||
@ -28,15 +27,15 @@ on myPeer:
|
||||
baz()
|
||||
```
|
||||
|
||||
### `%init_peer_id%`
|
||||
## `%init_peer_id%`
|
||||
|
||||
There is one custom peer ID that is always in scope: `%init_peer_id%`. It points to the peer that initiated this request.
|
||||
There is one custom peer ID that is always in scope: `%init_peer_id%`. It points to the peer that initiated this request.
|
||||
|
||||
{% hint style="warning" %}
|
||||
Using `on %init_peer_id%` is an anti-pattern: There is no way to ensure that init peer is accessible from the currently used part of the network.
|
||||
{% endhint %}
|
||||
|
||||
### More complex scenarios
|
||||
## More complex scenarios
|
||||
|
||||
Consider this example:
|
||||
|
||||
@ -44,16 +43,16 @@ Consider this example:
|
||||
func foo():
|
||||
on "peer foo":
|
||||
do_foo()
|
||||
|
||||
|
||||
func bar(i: i32):
|
||||
do_bar()
|
||||
|
||||
|
||||
func baz():
|
||||
bar(1)
|
||||
on "peer baz":
|
||||
foo()
|
||||
bar(2)
|
||||
bar(3)
|
||||
bar(3)
|
||||
```
|
||||
|
||||
Take a minute to think about:
|
||||
@ -70,7 +69,7 @@ Declarative topology definition always works the same way.
|
||||
* `bar(2)` is executed on `"peer baz"`, despite the fact that foo does topologic transition. `bar(2)` is in the scope of `on "peer baz"`, so it will be executed there
|
||||
* `bar(3)` is executed where `bar(1)` was: in the root scope of `baz`, wherever it was called from
|
||||
|
||||
### Accessing peers `via` other peers
|
||||
## Accessing peers `via` other peers
|
||||
|
||||
In a distributed network it is quite common that a peer is not directly accessible. For example, a browser has no public network interface and you cannot open a socket to a browser at will. Such constraints warrant a `relay` pattern: there should be a well-connected peer that relays requests from a peer to the network and vice versa.
|
||||
|
||||
@ -81,12 +80,12 @@ Relays are handled with `via`:
|
||||
-- the compiler will add an additional hop to some relay
|
||||
on "some peer" via "some relay":
|
||||
foo()
|
||||
|
||||
|
||||
-- More complex path: first go to relay2, then to relay1,
|
||||
-- then to peer. When going out of peer, do it in reverse
|
||||
on "peer" via relay1 via relay2:
|
||||
foo()
|
||||
|
||||
|
||||
-- You can pass any collection of strings to relay,
|
||||
-- and it will go through it if it's defined,
|
||||
-- or directly if not
|
||||
@ -137,7 +136,7 @@ foo()
|
||||
|
||||
When the `on` scope is ended, it does not affect any further topology moves. Until you stop indentation, `on` affects the topology and may add additional topology moves, which means more roundtrips and unnecessary latency.
|
||||
|
||||
### Callbacks
|
||||
## Callbacks
|
||||
|
||||
What if you want to return something to the initial peer? For example, implement a request-response pattern. Or send a bunch of requests to different peers, and render responses as they come, in any order.
|
||||
|
||||
@ -150,7 +149,7 @@ func run(updateModel: Model -> (), logMessage: string -> ()):
|
||||
updateModel(m)
|
||||
par on "other peer":
|
||||
x <- getMessage()
|
||||
logMessage(x)
|
||||
logMessage(x)
|
||||
```
|
||||
|
||||
Callbacks have the [arrow type](types.md#arrow-types).
|
||||
@ -161,15 +160,15 @@ If you pass just ordinary functions as arrow-type arguments, they will work as i
|
||||
func foo():
|
||||
on "peer 1":
|
||||
doFoo()
|
||||
|
||||
|
||||
func bar(cb: -> ()):
|
||||
on "peer2":
|
||||
cb()
|
||||
|
||||
|
||||
func baz():
|
||||
-- foo will go to peer 1
|
||||
-- bar will go to peer 2
|
||||
bar(foo)
|
||||
bar(foo)
|
||||
```
|
||||
|
||||
If you pass a service call as a callback, it will be executed locally on the node where you called it. That might change.
|
||||
@ -192,7 +191,7 @@ func baz():
|
||||
Passing service function calls as arguments is very fragile as it does not track that a service is resolved in the scope of the call. Abilities variance may fix that.
|
||||
{% endhint %}
|
||||
|
||||
### Parallel execution and topology
|
||||
## Parallel execution and topology
|
||||
|
||||
When blocks are executed in parallel, it is not always necessary to resolve the topology to get to the next peer. The compiler will add topologic hops from the par branch only if data defined in that branch is used down the flow.
|
||||
|
||||
@ -200,5 +199,3 @@ When blocks are executed in parallel, it is not always necessary to resolve the
|
||||
What if all branches do not return? Execution will halt. Be careful, use `co` if you don't care about the returned data.
|
||||
{% endhint %}
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Types
|
||||
|
||||
### Scalars
|
||||
## Scalars
|
||||
|
||||
Scalar types follow the Wasm IT notation.
|
||||
|
||||
@ -12,24 +12,24 @@ Scalar types follow the Wasm IT notation.
|
||||
* Records \(product type\): see below
|
||||
* Arrays: see Collection Types below
|
||||
|
||||
### Literals
|
||||
## Literals
|
||||
|
||||
You can pass booleans \(true, false\), numbers, double-quoted strings as literals.
|
||||
|
||||
### Products
|
||||
## Products
|
||||
|
||||
```python
|
||||
data ProductName:
|
||||
field_name: string
|
||||
|
||||
|
||||
data OtherProduct:
|
||||
product: ProductName
|
||||
flag: bool
|
||||
flag: bool
|
||||
```
|
||||
|
||||
Fields are accessible with the dot operator `.` , e.g. `product.field`.
|
||||
Fields are accessible with the dot operator `.` , e.g. `product.field`.
|
||||
|
||||
### Collection Types
|
||||
## Collection Types
|
||||
|
||||
Aqua has three different types with variable length, denoted by quantifiers `[]`, `*`, and `?`.
|
||||
|
||||
@ -41,7 +41,6 @@ Appendable collection with 0..N values: `*`
|
||||
|
||||
Any data type can be prepended with a quantifier, e.g. `*u32`, `[][]string`, `?ProductType` are all correct type specifications.
|
||||
|
||||
|
||||
You can access a distinct value of a collection with `!` operator, optionally followed by an index.
|
||||
|
||||
Examples:
|
||||
@ -60,7 +59,7 @@ maybe_value: ?string
|
||||
value = maybe_value!
|
||||
```
|
||||
|
||||
### Arrow Types
|
||||
## Arrow Types
|
||||
|
||||
Every function has an arrow type that maps a list of input types to an optional output type.
|
||||
|
||||
@ -82,7 +81,7 @@ arrow()
|
||||
x <- arrow()
|
||||
```
|
||||
|
||||
### Type Alias
|
||||
## Type Alias
|
||||
|
||||
For convenience, you can alias a type:
|
||||
|
||||
@ -90,13 +89,12 @@ For convenience, you can alias a type:
|
||||
alias MyAlias = ?string
|
||||
```
|
||||
|
||||
### Type Variance
|
||||
## Type Variance
|
||||
|
||||
Aqua is made for composing data on the open network. That means that you want to compose things if they do compose, even if you don't control its source code.
|
||||
|
||||
Therefore Aqua follows the structural typing paradigm: if a type contains all the expected data, then it fits. For example, you can pass `u8` in place of `u16` or `i16`. Or `?bool` in place of `[]bool`. Or `*string` instead of `?string` or `[]string`. The same holds for products.
|
||||
|
||||
|
||||
For arrow types, Aqua checks the variance on arguments and contravariance on the return type.
|
||||
|
||||
```text
|
||||
@ -130,17 +128,17 @@ bar(foo4)
|
||||
|
||||
Arrow type `A: D -> C` is a subtype of `A1: D1 -> C1`, if `D1` is a subtype of `D` and `C` is a subtype of `C1`.
|
||||
|
||||
### Type Of A Service And A File
|
||||
## Type Of A Service And A File
|
||||
|
||||
A service type is a product of arrows.
|
||||
|
||||
```text
|
||||
service MyService:
|
||||
foo(arg: string) -> bool
|
||||
|
||||
|
||||
-- type of this service is:
|
||||
data MyServiceType:
|
||||
foo: string -> bool
|
||||
foo: string -> bool
|
||||
```
|
||||
|
||||
The file is a product of all defined constants and functions \(treated as arrows\). Type definitions in the file do not go to the file type.
|
||||
@ -150,16 +148,14 @@ The file is a product of all defined constants and functions \(treated as arrows
|
||||
|
||||
func foo(arg: string) -> bool:
|
||||
...
|
||||
|
||||
|
||||
const flag ?= true
|
||||
|
||||
-- type of MyFile.aqua
|
||||
data MyServiceType:
|
||||
foo: string -> bool
|
||||
flag: bool
|
||||
flag: bool
|
||||
```
|
||||
|
||||
{% embed url="https://github.com/fluencelabs/aqua/blob/main/types/src/main/scala/aqua/types/Type.scala" caption="See the types system implementation" %}
|
||||
|
||||
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ on "peer 1":
|
||||
|
||||
More on that in the Security section. Now let's see how we can work with values inside the language.
|
||||
|
||||
### Arguments
|
||||
## Arguments
|
||||
|
||||
Function arguments are available within the whole function body.
|
||||
|
||||
@ -26,14 +26,14 @@ Function arguments are available within the whole function body.
|
||||
func foo(arg: i32, log: string -> ()):
|
||||
-- Use data arguments
|
||||
bar(arg)
|
||||
|
||||
|
||||
-- Arguments can have arrow type and be used as strings
|
||||
log("Wrote arg to responses")
|
||||
```
|
||||
|
||||
### Return values
|
||||
## Return values
|
||||
|
||||
You can assign results of an arrow call to a name, and use this returned value in the code below.
|
||||
You can assign results of an arrow call to a name, and use this returned value in the code below.
|
||||
|
||||
```text
|
||||
-- Imagine a Stringify service that's always available
|
||||
@ -47,7 +47,7 @@ func bar(arg: i32) -> string:
|
||||
-- Starting from there, you can use x
|
||||
-- Pass x out of the function scope as the return value
|
||||
<- x
|
||||
|
||||
|
||||
|
||||
func foo(arg: i32, log: *string):
|
||||
-- Use bar to convert arg to string, push that string
|
||||
@ -55,7 +55,7 @@ func foo(arg: i32, log: *string):
|
||||
log <- bar(arg)
|
||||
```
|
||||
|
||||
### Literals
|
||||
## Literals
|
||||
|
||||
Aqua supports just a few literals: numbers, quoted strings, booleans. You [cannot init a structure](https://github.com/fluencelabs/aqua/issues/167) in Aqua, only obtain it as a result of a function call.
|
||||
|
||||
@ -67,7 +67,7 @@ foo("double quoted string literal")
|
||||
-- Booleans are true or false
|
||||
if x == false:
|
||||
foo("false is a literal")
|
||||
|
||||
|
||||
-- Numbers are different
|
||||
-- Any number:
|
||||
bar(1)
|
||||
@ -79,9 +79,9 @@ bar(-1)
|
||||
bar(-0.2)
|
||||
```
|
||||
|
||||
### Getters
|
||||
## Getters
|
||||
|
||||
In Aqua, you can use a getter to peak into a field of a product or indexed element in an array.
|
||||
In Aqua, you can use a getter to peak into a field of a product or indexed element in an array.
|
||||
|
||||
```text
|
||||
data Sub:
|
||||
@ -91,7 +91,7 @@ data Example:
|
||||
field: u32
|
||||
arr: []Sub
|
||||
child: Sub
|
||||
|
||||
|
||||
func foo(e: Example):
|
||||
bar(e.field) -- u32
|
||||
bar(e.child) -- Sub
|
||||
@ -100,14 +100,13 @@ func foo(e: Example):
|
||||
bar(e.arr!) -- gets the 0 element
|
||||
bar(e.arr!.sub) -- string
|
||||
bar(e.arr!2) -- gets the 2nd element
|
||||
bar(e.arr!2.sub) -- string
|
||||
bar(e.arr!2.sub) -- string
|
||||
```
|
||||
|
||||
Note that the `!` operator may fail or halt:
|
||||
|
||||
* If it is called on an immutable collection, it will fail if the collection is shorter and has no given index; you can handle the error with [try](operators/conditional.md#try) or [otherwise](operators/conditional.md#otherwise).
|
||||
* If it is called on an appendable stream, it will wait for some parallel append operation to fulfill, see [Join behavior](operators/parallel.md#join-behavior).
|
||||
|
||||
* If it is called on an immutable collection, it will fail if the collection is shorter and has no given index; you can handle the error with [try](https://github.com/fluencelabs/aqua-book/tree/d54b086ab43f89c9f5622d26a22574a47d0cde19/language/operators/conditional.md#try) or [otherwise](https://github.com/fluencelabs/aqua-book/tree/d54b086ab43f89c9f5622d26a22574a47d0cde19/language/operators/conditional.md#otherwise).
|
||||
* If it is called on an appendable stream, it will wait for some parallel append operation to fulfill, see [Join behavior](https://github.com/fluencelabs/aqua-book/tree/d54b086ab43f89c9f5622d26a22574a47d0cde19/language/operators/parallel.md#join-behavior).
|
||||
|
||||
{% hint style="warning" %}
|
||||
The `!` operator can currently only be used with literal indices.
|
||||
@ -115,11 +114,10 @@ That is,`!2` is valid but`!x` is not valid.
|
||||
We expect to address this limitation soon.
|
||||
{% endhint %}
|
||||
|
||||
### Assignments
|
||||
## Assignments
|
||||
|
||||
Assignments, `=`, only give a name to a value with applied getter or to a literal.
|
||||
|
||||
|
||||
```text
|
||||
func foo(arg: bool, e: Example):
|
||||
-- Rename the argument
|
||||
@ -130,7 +128,7 @@ func foo(arg: bool, e: Example):
|
||||
c = "just string value"
|
||||
```
|
||||
|
||||
### Constants
|
||||
## Constants
|
||||
|
||||
Constants are like assignments but in the root scope. They can be used in all function bodies, textually below the place of const definition. Constant values must resolve to a literal.
|
||||
|
||||
@ -150,7 +148,7 @@ func bar():
|
||||
foo(setting)
|
||||
```
|
||||
|
||||
### Visibility scopes
|
||||
## Visibility scopes
|
||||
|
||||
Visibility scopes follow the contracts of execution flow.
|
||||
|
||||
@ -161,7 +159,7 @@ Functions have isolated scopes:
|
||||
```text
|
||||
func foo():
|
||||
a = 5
|
||||
|
||||
|
||||
func bar():
|
||||
-- a is not defined in this function scope
|
||||
a = 7
|
||||
@ -176,9 +174,9 @@ func foo():
|
||||
for y <- ys:
|
||||
-- Can use what was defined above
|
||||
z <- bar(x)
|
||||
|
||||
|
||||
-- z is not defined in scope
|
||||
z = 7
|
||||
z = 7
|
||||
```
|
||||
|
||||
[Parallel](flow/parallel.md#join-behavior) branches have [no access](https://github.com/fluencelabs/aqua/issues/90) to each other's data:
|
||||
@ -193,7 +191,7 @@ par y <- bar(x)
|
||||
baz(x, y)
|
||||
```
|
||||
|
||||
Recovery branches in [conditional flow](operators/conditional.md) have no access to the main branch as the main branch exports values, whereas the recovery branch does not:
|
||||
Recovery branches in [conditional flow](https://github.com/fluencelabs/aqua-book/tree/d54b086ab43f89c9f5622d26a22574a47d0cde19/language/operators/conditional.md) have no access to the main branch as the main branch exports values, whereas the recovery branch does not:
|
||||
|
||||
```text
|
||||
try:
|
||||
@ -202,13 +200,12 @@ otherwise:
|
||||
-- this is not possible – will fail
|
||||
bar(x)
|
||||
y <- baz()
|
||||
|
||||
|
||||
-- y is not available below
|
||||
willFail(y)
|
||||
|
||||
willFail(y)
|
||||
```
|
||||
|
||||
### Streams as literals
|
||||
## Streams as literals
|
||||
|
||||
Stream is a special data structure that allows many writes. It has [a dedicated article](crdt-streams.md).
|
||||
|
||||
@ -225,13 +222,13 @@ par resp <- bar()
|
||||
for x <- xs:
|
||||
-- Write to a stream that's defined above
|
||||
resp <- baz()
|
||||
|
||||
|
||||
try:
|
||||
resp <- baz()
|
||||
otherwise:
|
||||
on "other peer":
|
||||
resp <- baz()
|
||||
|
||||
|
||||
-- Now resp can be used in place of arrays and optional values
|
||||
-- assume fn: []string -> ()
|
||||
fn(resp)
|
||||
@ -239,7 +236,7 @@ fn(resp)
|
||||
-- Can call fn with empty stream: you can use it
|
||||
-- to construct empty values of any collection types
|
||||
nilString: *string
|
||||
fn(nilString)
|
||||
fn(nilString)
|
||||
```
|
||||
|
||||
One of the most frequently used patterns for streams is [Conditional return](flow/conditional.md#conditional-return).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user