From 87f9acb305bda136f8142af08480bf01955f1738 Mon Sep 17 00:00:00 2001 From: mqxf Date: Wed, 29 Nov 2023 15:06:12 +0100 Subject: [PATCH 1/7] Started making descriptions --- examples/async-custom-entry/src/wasm.rs | 14 ++++++ examples/async-init/src/wasm.rs | 16 +++--- examples/async-recursion/src/wasm.rs | 9 ++++ examples/async-tester/src/lib.rs | 18 +++++++ examples/async-tester/src/wasm.rs | 56 +++++++++++++++++++++ examples/async/src/wasm.rs | 21 ++++++++ examples/autoreply/src/wasm.rs | 14 ++++++ examples/calc-hash/in-one-block/src/wasm.rs | 26 ++++++++++ examples/calc-hash/over-blocks/src/wasm.rs | 44 ++++++++++++++++ examples/calc-hash/src/lib.rs | 18 +++++++ examples/constructor/src/arg.rs | 18 +++++++ examples/constructor/src/builder.rs | 18 +++++++ examples/constructor/src/call.rs | 18 +++++++ examples/constructor/src/wasm.rs | 18 +++++++ 14 files changed, 301 insertions(+), 7 deletions(-) diff --git a/examples/async-custom-entry/src/wasm.rs b/examples/async-custom-entry/src/wasm.rs index a8f110f5bb2..c6b11fda280 100644 --- a/examples/async-custom-entry/src/wasm.rs +++ b/examples/async-custom-entry/src/wasm.rs @@ -16,6 +16,20 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program demonstrates the use of async `init` entry point, as well as custom entry point +//! functions for `handle_reply` and `handle_signal`, using of `gstd::async_init` and +//! `gstd::async_main` macros. +//! +//! `Init` is async and saves the source of the message it receives. +//! +//! `Handle` is async and goes into an infinite loop. +//! +//! `HandleReply` and `HandleSignal` are custom functions, defined as parameters in the +//! `gstd::async_init` macro. They send a message using [`send_bytes()`] containing their function name to the user saved +//! by the `Init` method. +//! +//! [`send_bytes()`]: msg::send_bytes + use gstd::{msg, ActorId}; static mut USER: ActorId = ActorId::zero(); diff --git a/examples/async-init/src/wasm.rs b/examples/async-init/src/wasm.rs index 0b12705ca91..fa4d824c41d 100644 --- a/examples/async-init/src/wasm.rs +++ b/examples/async-init/src/wasm.rs @@ -16,15 +16,17 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -//! The program demonstrates asynchronous execution and -//! how to use macros `gstd::async_init`/`gstd::async_main`. +//! This program demonstrates asynchronous execution and how to use macros `gstd::async_init` and +//! `gstd::async_main`. //! -//! `Init` method gets three addresses, sends "PING" messages -//! to them and waits for at least two replies with any payload ("approvals"). +//! `Init` is async and gets three addresses in the payload, sends "PING" messages to them and waits for +//! at least two replies with any payload ("approvals"). //! -//! `Handle` processes only "PING" messages. When `handle` gets such message -//! it sends empty requests to the three addresses and waits for just one approval. -//! If an approval is obtained the method replies with "PONG". +//! `Handle` is async and processes only "PING" messages. When `handle` gets such message it sends empty +//! requests to the three addresses and waits for just one approval. If an approval is obtained the +//! method sends a [`reply()`] with "PONG". +//! +//! [`reply()`]: msg::reply use crate::InputArgs; use futures::future; diff --git a/examples/async-recursion/src/wasm.rs b/examples/async-recursion/src/wasm.rs index 40648a95b08..e26c058bf24 100644 --- a/examples/async-recursion/src/wasm.rs +++ b/examples/async-recursion/src/wasm.rs @@ -16,6 +16,15 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program demonstrates the use of an async recursive function using the [`async_recursion`] +//! macro. +//! +//! `Init` method gets one address in the payload, which is saves. +//! +//! `Handle` is async and calls the recursive function with the payload as an i32 parameter `val`. +//! The function then sends a message with payload "PING" and awaits reply, then calls itself with +//! `val - reply.len()` while `val - reply.len() > 0`. + use async_recursion::async_recursion; use gstd::{msg, prelude::*, ActorId}; diff --git a/examples/async-tester/src/lib.rs b/examples/async-tester/src/lib.rs index d752d462007..d93c08f802b 100644 --- a/examples/async-tester/src/lib.rs +++ b/examples/async-tester/src/lib.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2022-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + #![cfg_attr(not(feature = "std"), no_std)] use parity_scale_codec::{Decode, Encode}; diff --git a/examples/async-tester/src/wasm.rs b/examples/async-tester/src/wasm.rs index fe32ce5f66e..c78cd4a4b1e 100644 --- a/examples/async-tester/src/wasm.rs +++ b/examples/async-tester/src/wasm.rs @@ -1,3 +1,59 @@ +// This file is part of Gear. + +// Copyright (C) 2022-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + +//! This program demonstrates the use of [`msg`] syscalls from an async environment. +//! +//! `Handle` is async and gets a [`Kind`] in the payload, executing a syscall based on the `Kind`, +//! and sending a message back to the source with the payload "PONG". +//! +//! [`Send`] uses the [`send_for_reply()`] syscall to send a message back to the source, containing +//! the `kind` in the payload. +//! +//! [`SendWithGas(gas)`] uses the [`send_with_gas_for_reply()`] syscall to send a message back to +//! the source, containing the `kind` in the payload, and `gas` as the gas limit. +//! +//! [`SendBytes`] uses the [`send_bytes_for_reply()`] syscall to send a message back to the source, +//! containing the `kind` encoded as bytes in the payload. +//! +//! [`SendBytesWithGas(gas)`] uses the [`send_bytes_with_gas_for_reply()`] syscall to send a message +//! back to the source, containing the `kind` encoded as bytes in the payload and `gas` as the gas +//! limit. +//! +//! [`SendCommit`] uses the [`MessageHandle`], pushing the `kind` encoded as bytes and using +//! [`commit_for_reply()`] to send the message back to the source. +//! +//! [`SendCommitWithGas(gas)`] uses the [`MessageHandle`], pushing the `kind` encoded as bytes and +//! using [`commit_with_gas_for_reply()`] to send the message back to the source with `gas` as the +//! gas limit. +//! +//! [`Send`]: Kind::Send +//! [`SendWithGas(gas)`]: Kind::SendWithGas +//! [`SendBytes`]: Kind::SendBytes +//! [`SendBytesWithGas(gas)`]: Kind::SendBytesWithGas +//! [`SendCommit`]: Kind::SendCommit +//! [`SendCommitWithGas(gas)`]: Kind::SendCommitWithGas +//! [`send_for_reply()`]: msg::send_for_reply +//! [`send_with_gas_for_reply()`]: msg::send_with_gas_for_reply +//! [`send_bytes_for_reply()`]: msg::send_bytes_for_reply +//! [`send_bytes_with_gas_for_reply()`]: msg::send_bytes_with_gas_for_reply +//! [`commit_for_reply()`]: MessageHandle::commit_for_reply +//! [`commit_with_gas_for_reply()`]: MessageHandle::commit_with_gas_for_reply + use crate::Kind; use gstd::{ msg::{self, MessageHandle}, diff --git a/examples/async/src/wasm.rs b/examples/async/src/wasm.rs index 1b12121d16f..946e7ef71e9 100644 --- a/examples/async/src/wasm.rs +++ b/examples/async/src/wasm.rs @@ -16,6 +16,27 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program demonstrates use of an async `handle` entry point using the `gstd::async_main` +//! macro. +//! +//! `Init` method gets an address of a program in the payload, which should accept "PING" messages +//! and reply with "PONG". +//! +//! `Handle` is async and gets a [`Command`] in the payload, executes a certain action based on it, +//! and send a [`reply()`] with a payload containing the id of the current message. There are two commands +//! that can be executed: [`Common`] and [`Mutex`]. +//! +//! [`Common`] sends three async messages to the ping program, with the payload "PING", +//! awaits the reply and asserts that the reply is "PONG". +//! +//! [`Mutex`] asynchronously locks the mutex, awaiting it, sends a message back to the +//! source of the current message, containing the current message id in the payload, and then +//! it sends a ping message, awaiting the reply and asserting that the reply is "PONG". +//! +//! [`Common`]: Command::Common +//! [`Mutex`]: Command::Mutex +//! [`reply()`]: msg::reply + use crate::Command; use gstd::{msg, prelude::*, sync::Mutex, ActorId}; diff --git a/examples/autoreply/src/wasm.rs b/examples/autoreply/src/wasm.rs index b015136606a..d24840c6e6e 100644 --- a/examples/autoreply/src/wasm.rs +++ b/examples/autoreply/src/wasm.rs @@ -16,6 +16,20 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program demonstrates receiving an autoreply after sending a message and creating a reply +//! deposit. It uses a flag `RECEIVED_AUTO_REPLY` which is false by default. +//! +//! `Init` method gets an address of a program in the payload, which will be sending the autoreply, +//! and saves it. +//! +//! `Handle` method sends the payload "Hi" to the saved address, as long as it is not zero. Then it +//! creates a reply deposit with `1_000_000_000` gas, to handle the reply. +//! +//! `HandleReply` receives the reply and sets a flag `RECEIVED_AUTO_REPLY` to `true`. +//! +//! `State` is a custom function which is exported, and it replies with the current value of the +//! flag `RECEIVED_AUTO_REPLY`. + use gstd::{debug, exec, msg, prelude::*, ActorId}; static mut DESTINATION: ActorId = ActorId::zero(); diff --git a/examples/calc-hash/in-one-block/src/wasm.rs b/examples/calc-hash/in-one-block/src/wasm.rs index 3ad360e3329..81534df3c6c 100644 --- a/examples/calc-hash/in-one-block/src/wasm.rs +++ b/examples/calc-hash/in-one-block/src/wasm.rs @@ -1,3 +1,29 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + +//! This program runs a hashing computation in one execution. +//! +//! `Handle` method gets a [`Package`] in the payload, and repeatedly calculates a sha256 hash, +//! until the [`Package`] is finished. Once it is done, a [`reply()`] is sent, containing the result in +//! the payload. +//! +//! [`reply()`]: msg::reply + use crate::Package; use gstd::msg; diff --git a/examples/calc-hash/over-blocks/src/wasm.rs b/examples/calc-hash/over-blocks/src/wasm.rs index 2cdc19f8526..4610c034260 100644 --- a/examples/calc-hash/over-blocks/src/wasm.rs +++ b/examples/calc-hash/over-blocks/src/wasm.rs @@ -1,3 +1,47 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + +//! This program runs a hashing computation over several executions. +//! +//! `Init` method gets a u64 `threshold` in the payload, and saves it. +//! +//! `Handle` method gets a [`Method`] in the payload, and it executes some code based on the method. +//! +//! [`Start { expected, id, src }`] uses the given values to make a new [`Package`], saving it in +//! a static `registry`, mapping the `id` to a [`Package`]. We check if the [`Package`] is finished, +//! and if it is, we [`reply()`] with the result in the payload. Otherwise, we [`wait()`], halting execution. +//! +//! [`Refuel(id)`] creates a message which is sent to this program, with the payload being +//! [`Calculate(id)`]. +//! +//! [`Calculate(id)`] checks that it has been called from this program, as it is a private method. +//! The [`Package`] is retrieved from the static `registry` based on the `id`. While we have more +//! gas than the `threshold`, we calculate the [`Package`] until it is finished. If out gas goes +//! below the `threshold`, the execution is halted. If the [`Package`] is finished, we [`wake()`] the +//! original message which sent the [`Start { expected, id, src }`]. +//! +//! [`Start { expected, id, src }`]: Method::Start +//! [`Refuel(id)`]: Method::Refuel +//! [`Calculate(id)`]: Method::Calculate +//! [`wait()`]: exec::wait +//! [`wake()`]: exec::wake +//! [`reply()`]: msg::reply + use crate::Method; use gstd::{exec, msg}; use types::Package; diff --git a/examples/calc-hash/src/lib.rs b/examples/calc-hash/src/lib.rs index fbf5ed779b0..854032ccd20 100644 --- a/examples/calc-hash/src/lib.rs +++ b/examples/calc-hash/src/lib.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + #![no_std] extern crate alloc; diff --git a/examples/constructor/src/arg.rs b/examples/constructor/src/arg.rs index b749bbc03b7..8de733aac47 100644 --- a/examples/constructor/src/arg.rs +++ b/examples/constructor/src/arg.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + use alloc::{ string::{String, ToString}, vec::Vec, diff --git a/examples/constructor/src/builder.rs b/examples/constructor/src/builder.rs index bf871191605..c839878a619 100644 --- a/examples/constructor/src/builder.rs +++ b/examples/constructor/src/builder.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + use crate::{Arg, Call}; use alloc::{boxed::Box, string::ToString, vec, vec::Vec}; use core::{fmt::Debug, ops::Deref}; diff --git a/examples/constructor/src/call.rs b/examples/constructor/src/call.rs index 2f14a20030c..53d84daa490 100644 --- a/examples/constructor/src/call.rs +++ b/examples/constructor/src/call.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + use crate::Arg; use alloc::{boxed::Box, string::String, vec::Vec}; use parity_scale_codec::{Decode, Encode}; diff --git a/examples/constructor/src/wasm.rs b/examples/constructor/src/wasm.rs index 3848d0516ef..52dea4369d0 100644 --- a/examples/constructor/src/wasm.rs +++ b/examples/constructor/src/wasm.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + use crate::{Call, Scheme}; use gstd::{collections::BTreeMap, msg, String, Vec}; From 3c378770533be153943f85791bd2b86433b183f8 Mon Sep 17 00:00:00 2001 From: mqxf Date: Thu, 30 Nov 2023 10:18:29 +0100 Subject: [PATCH 2/7] More docs --- examples/async-signal-entry/src/wasm.rs | 17 +++++++++++++++++ examples/delayed-reservation-sender/src/wasm.rs | 7 +++++++ examples/delayed-sender/src/wasm.rs | 13 +++++++++++++ 3 files changed, 37 insertions(+) diff --git a/examples/async-signal-entry/src/wasm.rs b/examples/async-signal-entry/src/wasm.rs index a9192d60fd4..e41d32b1012 100644 --- a/examples/async-signal-entry/src/wasm.rs +++ b/examples/async-signal-entry/src/wasm.rs @@ -16,6 +16,23 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program demonstrates the automatically generated `handle_signal` function when using +//! `gstd::async_init` or `gstd::async_main`. +//! +//! `Init` is async and gets an [`InitAction`] in the payload, if the action is +//! [`Panic`](InitAction::Panic), we send a message using [`send_for_reply()`] back to the source +//! containing "init" as the payload, and then we [`panic!()`](core::panic), triggering a signal. +//! +//! `Handle` is async and calls [`send()`] a message back to the source containing "handle_signal" +//! as the payload, then calls [`wait()`]. +//! +//! The automatically generated `handle_signal` contains a call to [`gstd::handle_signal()`] +//! +//! [`send_for_reply()`]: msg::send_for_reply +//! [`send()`]: msg::send +//! [`wait()`]: exec::wait +//! [`gstd::handle_signal()`]: gstd::handle_signal + use crate::InitAction; use gstd::{exec, msg}; diff --git a/examples/delayed-reservation-sender/src/wasm.rs b/examples/delayed-reservation-sender/src/wasm.rs index 8887f1203ec..dc13a527c99 100644 --- a/examples/delayed-reservation-sender/src/wasm.rs +++ b/examples/delayed-reservation-sender/src/wasm.rs @@ -16,6 +16,13 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract calls [`send_bytes_delayed_from_reservation()`] with an empty payload and a +//! reservation id created by the input provided to the contract. It can either instantly call +//! the send syscall, or it can be asked to [`wait_for()`](exec::wait_for) a given amount of blocks +//! before calling it. +//! +//! [`send_bytes_delayed_from_reservation()`]: msg::send_bytes_delayed_from_reservation + use crate::{ReservationSendingShowcase, SENDING_EXPECT}; use gstd::{exec, msg, prelude::*, ReservationId}; diff --git a/examples/delayed-sender/src/wasm.rs b/examples/delayed-sender/src/wasm.rs index 16e8a6a1b66..577b8fa7ba9 100644 --- a/examples/delayed-sender/src/wasm.rs +++ b/examples/delayed-sender/src/wasm.rs @@ -16,6 +16,19 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract shows the use of `delayed` syscalls, which make the syscall wait a given number +//! of blocks before being executed. +//! +//! The `init()` function calls [`send_bytes_delayed()`](msg::send_bytes_delayed), with a delay +//! which is taken from the payload. +//! +//! The `handle()` method, when given any non empty payload, will save the current message id, and +//! then call [`wait()`](exec::wait). A second execution of the `handle()` method will call +//! [`wake_delayed()`](exec::wake_delayed) with the saved message id, and a delay which is taken +//! from the payload. If the payload is empty however, it will +//! [`send_bytes_delayed()`](msg::send_bytes_delayed) twice to the source, with an empty payload +//! and a delay of [`DELAY`](crate::DELAY). + use crate::DELAY; use gstd::{exec, msg, MessageId}; From 1aba39f9b96ca92a02466aaa455a98fb6ea46fca Mon Sep 17 00:00:00 2001 From: mqxf Date: Thu, 30 Nov 2023 13:59:20 +0100 Subject: [PATCH 3/7] More docs --- examples/distributor/src/wasm.rs | 7 ++++++ examples/fungible-token/src/wasm.rs | 7 ++++++ examples/futures-unordered/src/wasm.rs | 14 ++++++++++++ examples/gas-burned/build.rs | 18 +++++++++++++++ examples/gas-burned/src/lib.rs | 18 +++++++++++++++ examples/gas-burned/src/wasm.rs | 22 +++++++++++++++++++ .../incomplete-async-payloads/src/wasm.rs | 16 ++++++++++++++ examples/init-fail-sender/src/lib.rs | 18 +++++++++++++++ examples/init-fail-sender/src/wasm.rs | 22 +++++++++++++++++++ examples/init-wait-reply-exit/src/lib.rs | 18 +++++++++++++++ examples/init-wait-reply-exit/src/wasm.rs | 21 ++++++++++++++++++ examples/init-wait/src/wasm.rs | 4 ++++ examples/messager/src/wasm.rs | 4 ++++ examples/mul-by-const/src/lib.rs | 7 ------ examples/mul-by-const/src/wasm.rs | 9 +++----- examples/ncompose/src/lib.rs | 7 ------ examples/ncompose/src/wasm.rs | 9 +++----- examples/new-meta/src/wasm.rs | 22 +++++++++++++++++++ examples/node/src/wasm.rs | 20 +++++++++++++++++ examples/out-of-memory/src/wasm.rs | 2 ++ examples/piggy-bank/src/wasm.rs | 4 ++++ examples/ping/src/wasm.rs | 2 ++ 22 files changed, 245 insertions(+), 26 deletions(-) diff --git a/examples/distributor/src/wasm.rs b/examples/distributor/src/wasm.rs index 0fd4ce4b30d..9aba7ff2b11 100644 --- a/examples/distributor/src/wasm.rs +++ b/examples/distributor/src/wasm.rs @@ -16,6 +16,13 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract allows for a tree of programs to store values. When receiving a value, a program, +//! which is a node in the tree, will try to distribute the value to its subnodes, keeping the +//! leftover and any failed subnodes amounts for itself. Subnodes are assumed to be running the +//! same code, resulting in them distributing any value they get over their respective subnodes. +//! A subnode can be added via a request, containing the ActorId of the subnode. The final request +//! which can be sent will reply with the current value of this node. + use crate::{Program, Reply, Request}; use core::future::Future; use gstd::{collections::BTreeSet, debug, msg, prelude::*, sync::Mutex, ActorId}; diff --git a/examples/fungible-token/src/wasm.rs b/examples/fungible-token/src/wasm.rs index 9840581aeab..6dd95bb7ea8 100644 --- a/examples/fungible-token/src/wasm.rs +++ b/examples/fungible-token/src/wasm.rs @@ -16,6 +16,13 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! Smart contract for fungible tokens. When initializing, it is provided with the name, symbol, +//! decimals and initial amount of accounts. When reading the state through the `state` function, +//! we remove the fungible token from the program memory. The `handle` method allows us to interact +//! with the fungible token. We can read the balance of an account, or read the total supply. We can +//! also make transfers between two accounts, approve tokens for allowances, burn tokens from our +//! account and mint tokens to our account. + use core::ops::Range; use ft_io::*; use gstd::{msg, prelude::*, ActorId}; diff --git a/examples/futures-unordered/src/wasm.rs b/examples/futures-unordered/src/wasm.rs index dcc301caaf2..a9b818dd05b 100644 --- a/examples/futures-unordered/src/wasm.rs +++ b/examples/futures-unordered/src/wasm.rs @@ -16,6 +16,20 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract shows 3 ways of running two separate futures (async blocks). The contract is given +//! two addresses of two programs, "async" and "ping". The `handle` method is given a command, which +//! tells it which method to use to run the two futures. Each future sends a message to the given +//! program, containing an empty vec and "PING" as the payload respectively. +//! +//! [`Unordered`](Command::Unordered) uses [`FuturesUnordered`] and runs the two futures +//! sequentially, waiting for one to finish before running the next. +//! +//! [`Select`](Command::Select) uses [`select_biased`] to run both futures concurrently, waiting for +//! the future that completes first. +//! +//! [`Join`](Command::Join) uses [`join`] to run both futures concurrently, waiting for both futures +//! to complete. + use crate::Command; use futures::{ join, select_biased, diff --git a/examples/gas-burned/build.rs b/examples/gas-burned/build.rs index 6836d02c06d..4c502a3ddee 100644 --- a/examples/gas-burned/build.rs +++ b/examples/gas-burned/build.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + fn main() { gear_wasm_builder::build(); } diff --git a/examples/gas-burned/src/lib.rs b/examples/gas-burned/src/lib.rs index 45e628fea74..19f9b867639 100644 --- a/examples/gas-burned/src/lib.rs +++ b/examples/gas-burned/src/lib.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + #![cfg_attr(not(feature = "std"), no_std)] #[cfg(feature = "std")] diff --git a/examples/gas-burned/src/wasm.rs b/examples/gas-burned/src/wasm.rs index 9e4fcf19f35..da70be1995f 100644 --- a/examples/gas-burned/src/wasm.rs +++ b/examples/gas-burned/src/wasm.rs @@ -1,3 +1,25 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + +//! This smart contract is used to test burning gas. The `init` and `handle` functions both create +//! a [`Vec`] of lengths [`SHORT`] and [`LONG`] respectively, then set each element in the vector +//! to the index of the element, squared. + use gstd::{msg, prelude::*}; const SHORT: usize = 100; diff --git a/examples/incomplete-async-payloads/src/wasm.rs b/examples/incomplete-async-payloads/src/wasm.rs index 987f22ff05d..26451c1fc35 100644 --- a/examples/incomplete-async-payloads/src/wasm.rs +++ b/examples/incomplete-async-payloads/src/wasm.rs @@ -16,6 +16,22 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract gets an address of a ping program when initialized. It can be sent one of four +//! commands. +//! +//! [`HandleStore`](Command::HandleStore) will create a new [`MessageHandle`], push some data to it, +//! ping the ping program, then push some more data and commit the reply. +//! +//! [`ReplyStore`](Command::ReplyStore) will push some data to the default reply, ping the ping +//! program, then push some more data and commit the reply. +//! +//! [`Handle`](Command::Handle) will create a new [`MessageHandle`] and push some data to it, then +//! commit the reply. +//! +//! [`Reply`](Command::Reply) will push some data to the default reply, then commit the reply. +//! +//! [`MessageHandle`]: msg::MessageHandle + use crate::Command; use gstd::{ msg::{self, MessageHandle}, diff --git a/examples/init-fail-sender/src/lib.rs b/examples/init-fail-sender/src/lib.rs index a9c048cd09d..a9c22cfef78 100644 --- a/examples/init-fail-sender/src/lib.rs +++ b/examples/init-fail-sender/src/lib.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + #![cfg_attr(not(feature = "std"), no_std)] #[cfg(feature = "std")] diff --git a/examples/init-fail-sender/src/wasm.rs b/examples/init-fail-sender/src/wasm.rs index 4bca976c3bb..7ac38eeaff2 100644 --- a/examples/init-fail-sender/src/wasm.rs +++ b/examples/init-fail-sender/src/wasm.rs @@ -1,3 +1,25 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + +//! This contract will get an address, then send an empty payload to it, then send another empty +//! payload, waiting for a reply, then postpone handling for a set number of blocks, given by +//! [`reply_duration()`](super::reply_duration), and then panicking. + use gstd::{msg, ActorId}; #[gstd::async_init] diff --git a/examples/init-wait-reply-exit/src/lib.rs b/examples/init-wait-reply-exit/src/lib.rs index 813a4f3ed30..f085dcc541e 100644 --- a/examples/init-wait-reply-exit/src/lib.rs +++ b/examples/init-wait-reply-exit/src/lib.rs @@ -1,3 +1,21 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + #![cfg_attr(not(feature = "std"), no_std)] #[cfg(feature = "std")] diff --git a/examples/init-wait-reply-exit/src/wasm.rs b/examples/init-wait-reply-exit/src/wasm.rs index b8ee47f709e..5cff8280dbd 100644 --- a/examples/init-wait-reply-exit/src/wasm.rs +++ b/examples/init-wait-reply-exit/src/wasm.rs @@ -1,3 +1,24 @@ +// This file is part of Gear. + +// Copyright (C) 2021-2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + +//! This contract has an async `init` function, which sends a message to the source, awaiting a +//! reply, then exiting the program from within the init method. + use gstd::{ exec, msg, prelude::{vec, *}, diff --git a/examples/init-wait/src/wasm.rs b/examples/init-wait/src/wasm.rs index 7d3ecdc3f0b..5ad8a7fc186 100644 --- a/examples/init-wait/src/wasm.rs +++ b/examples/init-wait/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract shows how a program may call [`wait()`](exec::wait) from the `init` function, +//! after sending a message to some other address, in this case, the source of the message. +//! When receiving a reply, this program will wake the init message and finish initializing. + use gstd::{collections::BTreeMap, exec, msg, MessageId}; #[derive(PartialEq, Debug)] diff --git a/examples/messager/src/wasm.rs b/examples/messager/src/wasm.rs index 68bbbed8179..72d27ef139d 100644 --- a/examples/messager/src/wasm.rs +++ b/examples/messager/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract will send an empty message with a value provided by the payload back to the source +//! when initialized. `handle` and `handle_reply` will send a message containing [`SEND_REPLY`] and +//! [`REPLY_REPLY`] back to the source respectively. + use crate::{REPLY_REPLY, SEND_REPLY}; use gstd::msg; diff --git a/examples/mul-by-const/src/lib.rs b/examples/mul-by-const/src/lib.rs index cc2e84c6fc0..f085dcc541e 100644 --- a/examples/mul-by-const/src/lib.rs +++ b/examples/mul-by-const/src/lib.rs @@ -16,13 +16,6 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -// This contract recursively composes itself with another contract (the other contract -// being applied to the input data first): `c(f) = (c(f) . f) x`. -// Every call to the auto_composer contract increments the internal `ITER` counter. -// As soon as the counter reaches the `MAX_ITER`, the recursion stops. -// Effectively, this procedure executes a composition of `MAX_ITER` contracts `f` -// where the output of the previous call is fed to the input of the next call. - #![cfg_attr(not(feature = "std"), no_std)] #[cfg(feature = "std")] diff --git a/examples/mul-by-const/src/wasm.rs b/examples/mul-by-const/src/wasm.rs index 15dfeb404c8..ee5a6d8d963 100644 --- a/examples/mul-by-const/src/wasm.rs +++ b/examples/mul-by-const/src/wasm.rs @@ -16,12 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -// This contract recursively composes itself with another contract (the other contract -// being applied to the input data first): `c(f) = (c(f) . f) x`. -// Every call to the auto_composer contract increments the internal `ITER` counter. -// As soon as the counter reaches the `MAX_ITER`, the recursion stops. -// Effectively, this procedure executes a composition of `MAX_ITER` contracts `f` -// where the output of the previous call is fed to the input of the next call. +//! This contract recursively multiplies a state by a number. A value is provided during `init`, +//! and it is saved along with the program id. `handle` is given another value in the payload, +//! which it uses to multiply the state, saving the new state and replying with the new state. extern crate alloc; diff --git a/examples/ncompose/src/lib.rs b/examples/ncompose/src/lib.rs index cc2e84c6fc0..f085dcc541e 100644 --- a/examples/ncompose/src/lib.rs +++ b/examples/ncompose/src/lib.rs @@ -16,13 +16,6 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -// This contract recursively composes itself with another contract (the other contract -// being applied to the input data first): `c(f) = (c(f) . f) x`. -// Every call to the auto_composer contract increments the internal `ITER` counter. -// As soon as the counter reaches the `MAX_ITER`, the recursion stops. -// Effectively, this procedure executes a composition of `MAX_ITER` contracts `f` -// where the output of the previous call is fed to the input of the next call. - #![cfg_attr(not(feature = "std"), no_std)] #[cfg(feature = "std")] diff --git a/examples/ncompose/src/wasm.rs b/examples/ncompose/src/wasm.rs index 1b4c1276c5e..8084fde498f 100644 --- a/examples/ncompose/src/wasm.rs +++ b/examples/ncompose/src/wasm.rs @@ -16,12 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -// This contract recursively composes itself with another contract (the other contract -// being applied to the input data first): `c(f) = (c(f) . f) x`. -// Every call to the auto_composer contract increments the internal `ITER` counter. -// As soon as the counter reaches the `MAX_ITER`, the recursion stops. -// Effectively, this procedure executes a composition of `MAX_ITER` contracts `f` -// where the output of the previous call is fed to the input of the next call. +//! This contract will recursively call itself and some other program, given during `init`, up until +//! a certain depth, `max_iter` is reached, providing a [`Vec`] in the payload, being the output +//! of the previous call. Once the iteration is done, the resulting vector is sent in a reply. extern crate alloc; diff --git a/examples/new-meta/src/wasm.rs b/examples/new-meta/src/wasm.rs index 906aaee1b44..4a40caaf0d0 100644 --- a/examples/new-meta/src/wasm.rs +++ b/examples/new-meta/src/wasm.rs @@ -1,3 +1,25 @@ +// This file is part of Gear. + +// Copyright (C) 2023 Gear Technologies Inc. +// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0 + +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . + +//! This contract creates a [`Vec`] of wallets. The `handle` function gets one of the wallets +//! based on an id, and replies with it. The `state` function will return a copy of the vector +//! of wallets. + use crate::{MessageIn, MessageInitIn, MessageInitOut, MessageOut, Wallet}; use gstd::{msg, prelude::*}; diff --git a/examples/node/src/wasm.rs b/examples/node/src/wasm.rs index 83c9acefa07..326a6d77614 100644 --- a/examples/node/src/wasm.rs +++ b/examples/node/src/wasm.rs @@ -16,6 +16,26 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract contains a node state, which is created during `init`, using the input for the +//! status. The `handle` method sends a request to the node: +//! +//! `IsReady` - returns `Yes` if the transition is empty, `No` otherwise. +//! +//! `Begin(Operation)` - starts a transition if one is not already in progress, if there are +//! subnodes, the request it sent to the subnode, and the program calls [`wait()`](exec::wait). +//! Otherwise, it sets the transition state to `Ready` and returns `Success`. +//! +//! `Commit` - checks if there are subnodes, if there are, and the transition state is `Ready`, it +//! sends the request to the first subnode, and the program calls [`wait()`](exec::wait). Otherwise, +//! it check that the current transition was called by the same source that this message is sent +//! from, and if so, it ends the transition and returns `Success`. +//! +//! `Add(ActorId)` - adds a subnode to the program state. +//! +//! The `handle_reply` method verifies that the message was sent from the correct source for the +//! current transition, and if so, wakes the message which was waited. If the reply failed, it +//! sets the transition state to `Failed`. + use crate::{Initialization, Operation, Reply, Request}; use gstd::{collections::BTreeSet, debug, exec, msg, prelude::*, ActorId, MessageId}; diff --git a/examples/out-of-memory/src/wasm.rs b/examples/out-of-memory/src/wasm.rs index 6ac5382b67a..afb264e1404 100644 --- a/examples/out-of-memory/src/wasm.rs +++ b/examples/out-of-memory/src/wasm.rs @@ -16,6 +16,8 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program signals an allocation error of a massive byte array. + use alloc::alloc::Layout; #[no_mangle] diff --git a/examples/piggy-bank/src/wasm.rs b/examples/piggy-bank/src/wasm.rs index cc8ea523c1c..7b5d9f949d5 100644 --- a/examples/piggy-bank/src/wasm.rs +++ b/examples/piggy-bank/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program loads the payload directly from the stack, and if the payload is "smash", then it +//! sends all the available value in the reply, otherwise it keeps any value it was given in the +//! program. + use gstd::{debug, exec, msg}; #[no_mangle] diff --git a/examples/ping/src/wasm.rs b/examples/ping/src/wasm.rs index 69b988852d2..d6b3963aa43 100644 --- a/examples/ping/src/wasm.rs +++ b/examples/ping/src/wasm.rs @@ -16,6 +16,8 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! Ping contract, when it receives a message with the payload "PING", it replies with "PONG". + use gstd::{msg, prelude::*}; #[no_mangle] From 2f0045c7aacf19c1532f9c4450b13037a9d9a017 Mon Sep 17 00:00:00 2001 From: mqxf Date: Thu, 30 Nov 2023 16:55:32 +0100 Subject: [PATCH 4/7] Docs made (except those that were skipped) --- examples/program-generator/src/wasm.rs | 3 +++ examples/proxy-relay/src/wasm.rs | 5 +++++ examples/proxy-reservation-with-gas/src/wasm.rs | 3 +++ examples/proxy/src/wasm.rs | 3 +++ examples/read-big-state/src/wasm.rs | 3 +++ examples/reservation-manager/src/wasm.rs | 3 +++ examples/reserve-gas/src/wasm.rs | 6 ++++++ examples/rwlock/src/wasm.rs | 4 ++++ examples/send-from-reservation/src/wasm.rs | 8 ++++++++ examples/signal-entry/src/wasm.rs | 14 ++++++++++++++ examples/state-rollback/src/wasm.rs | 3 +++ examples/sync-duplicate/src/wasm.rs | 4 ++++ examples/sys-calls/src/wasm.rs | 3 +++ examples/syscall-error/src/wasm.rs | 2 ++ examples/vec/src/wasm.rs | 4 ++++ examples/wait-timeout/src/wasm.rs | 4 ++++ examples/wait/src/wasm.rs | 5 +++++ examples/wait_wake/src/wasm.rs | 4 ++++ examples/waiter/src/wasm.rs | 4 ++++ examples/waiting-proxy/src/wasm.rs | 3 +++ 20 files changed, 88 insertions(+) diff --git a/examples/program-generator/src/wasm.rs b/examples/program-generator/src/wasm.rs index cdf11b1a684..e9f7c56f1be 100644 --- a/examples/program-generator/src/wasm.rs +++ b/examples/program-generator/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This smart contract tests the [`ProgramGenerator`], by creating a program with a predefined +//! `CodeId`, and then checking that the salts this generates are all unique. + use gstd::{collections::BTreeSet, prelude::*, prog::ProgramGenerator, CodeId}; fn check_salt_uniqueness() { diff --git a/examples/proxy-relay/src/wasm.rs b/examples/proxy-relay/src/wasm.rs index 8e5f1594df4..78c09ab789a 100644 --- a/examples/proxy-relay/src/wasm.rs +++ b/examples/proxy-relay/src/wasm.rs @@ -16,6 +16,11 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program acts like a relay, where in `init`, a certain setting is given to it, and based +//! on that setting, it handles messages differently. It can proxy the messages to other programs, +//! do so with gas, reply or reply with gas, and it can also send multiple messages using a +//! [`MessageHandle`] to a predefined destination. + use crate::{RelayCall, ResendPushData}; use gstd::msg::{self, MessageHandle}; diff --git a/examples/proxy-reservation-with-gas/src/wasm.rs b/examples/proxy-reservation-with-gas/src/wasm.rs index 695e6678d4b..4d66fb2a710 100644 --- a/examples/proxy-reservation-with-gas/src/wasm.rs +++ b/examples/proxy-reservation-with-gas/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract creates a reservation for a certain amount of gas, and then sends a message from +//! this reservation with a delay to some destination. + use crate::InputArgs; use gstd::{msg, ActorId, ReservationId}; diff --git a/examples/proxy/src/wasm.rs b/examples/proxy/src/wasm.rs index b4c78b974c3..f68a773a60a 100644 --- a/examples/proxy/src/wasm.rs +++ b/examples/proxy/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This smart contract acts like a proxy to another contract. The other program is given to it +//! in the `init` method, and any messages sent to it are forwarded to the other contract. + use crate::{InputArgs, HANDLE_REPLY_EXPECT}; use gstd::{msg, ActorId}; diff --git a/examples/read-big-state/src/wasm.rs b/examples/read-big-state/src/wasm.rs index 65f13db548c..e8b88aceb8e 100644 --- a/examples/read-big-state/src/wasm.rs +++ b/examples/read-big-state/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program has a large state, which is filled with strings from the `handle` method. We can +//! then call the `state` method to read the large state. + use crate::State; use gstd::{msg, prelude::*}; diff --git a/examples/reservation-manager/src/wasm.rs b/examples/reservation-manager/src/wasm.rs index a9d81564c0b..52c7daf3227 100644 --- a/examples/reservation-manager/src/wasm.rs +++ b/examples/reservation-manager/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program allows you to reserve gas multiple times, with different durations and gas amounts. +//! It can also send a message from the reservation that was previously created. + use crate::Action; use gstd::{msg, prelude::*, Reservations}; diff --git a/examples/reserve-gas/src/wasm.rs b/examples/reserve-gas/src/wasm.rs index 09e1d4ab2d9..593949fff0c 100644 --- a/examples/reserve-gas/src/wasm.rs +++ b/examples/reserve-gas/src/wasm.rs @@ -16,6 +16,12 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program is a reservation system, it has a list of reservations, and has several functions +//! that can be used from the `handle` method. It also has the option to wait during the `init` +//! method, needing to be awakened by a reply in the `handle_reply` method. You are able to reserve, +//! unreserve, use the reserved gas to send a message or reply, or send a message and unreserve the +//! gas. + use crate::{ HandleAction, InitAction, ReplyAction, REPLY_FROM_RESERVATION_PAYLOAD, RESERVATION_AMOUNT, }; diff --git a/examples/rwlock/src/wasm.rs b/examples/rwlock/src/wasm.rs index 813f733a4b1..8f7131bd5fb 100644 --- a/examples/rwlock/src/wasm.rs +++ b/examples/rwlock/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program shows the use of a [`RwLock`] from an async context. Showing both reading and +//! writing from the lock, aswell as waiting for a ping program while having the lock, keeping +//! other executions from using the lock. + use crate::Command; use core::{ future::Future, diff --git a/examples/send-from-reservation/src/wasm.rs b/examples/send-from-reservation/src/wasm.rs index a8281f605ec..50848ee9d53 100644 --- a/examples/send-from-reservation/src/wasm.rs +++ b/examples/send-from-reservation/src/wasm.rs @@ -16,6 +16,14 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program shows all the different ways to send a message from a reservation. This includes: +//! - Send to user +//! - Send to user delayed +//! - Send to program +//! - Send to program delayed +//! - Reply to user +//! - Reply to program (by calling itself) + use crate::HandleAction; use gstd::{msg, prelude::*, ReservationId}; diff --git a/examples/signal-entry/src/wasm.rs b/examples/signal-entry/src/wasm.rs index 302d99bbf59..eaf93f9d0b8 100644 --- a/examples/signal-entry/src/wasm.rs +++ b/examples/signal-entry/src/wasm.rs @@ -16,6 +16,20 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program shows the use of the `handle_signal` entry point, which is reserved for system +//! usage in the case of some error during an execution, such as: +//! +//! - Panic after wait and system reserve gas +//! - Panic after system reserve gas +//! - Accumulate system gas reserves (and usages of the gas) across waits +//! - Run out of gas from execution +//! - Forbidden action (send message to system address) +//! - Run out of memory +//! - unreachable!() +//! - Invalid debug!() +//! - Unrecoverable ext error +//! - Invalid free() call + use crate::{HandleAction, WAIT_AND_RESERVE_WITH_PANIC_GAS}; use gear_core::ids::ProgramId; use gstd::{ diff --git a/examples/state-rollback/src/wasm.rs b/examples/state-rollback/src/wasm.rs index 6499386ef5e..41f61780c5a 100644 --- a/examples/state-rollback/src/wasm.rs +++ b/examples/state-rollback/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program sends the previous payload (if any) to the source, then saves the new payload. +//! If the new payload is "panic" or "leave", the program panics or leaves respectively. + use gstd::{exec, msg, prelude::*}; static mut PAYLOAD: Option> = None; diff --git a/examples/sync-duplicate/src/wasm.rs b/examples/sync-duplicate/src/wasm.rs index f949f4afdcd..6b633da7ee3 100644 --- a/examples/sync-duplicate/src/wasm.rs +++ b/examples/sync-duplicate/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program increments a counter and sends a message in an async block, before resetting the +//! counter back to 0. If a second message happens while the first is waiting for the reply, the +//! counter will be at 2. + use gstd::{msg, prelude::*, ActorId}; static mut COUNTER: i32 = 0; diff --git a/examples/sys-calls/src/wasm.rs b/examples/sys-calls/src/wasm.rs index 9b6a8d39a1f..f73dd52faa4 100644 --- a/examples/sys-calls/src/wasm.rs +++ b/examples/sys-calls/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program allows you to send a list of syscalls and other minor fucntions that it should +//! execute. + use crate::Kind; use gstd::{ errors::{ReplyCode, SignalCode, SimpleExecutionError}, diff --git a/examples/syscall-error/src/wasm.rs b/examples/syscall-error/src/wasm.rs index 74a45d9a3aa..4ee481247f4 100644 --- a/examples/syscall-error/src/wasm.rs +++ b/examples/syscall-error/src/wasm.rs @@ -16,6 +16,8 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program sends a message to an invalid id, asserting that it returns an error. + use gstd::{ errors::{Error, ExtError, MessageError}, msg, diff --git a/examples/vec/src/wasm.rs b/examples/vec/src/wasm.rs index fe0eeb50827..cb6c69c70fd 100644 --- a/examples/vec/src/wasm.rs +++ b/examples/vec/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program allows you to make a vector of a given length, and then it will debug print +//! the pointer address of the last element of the vector. It will also save how many requests +//! have been made to make new vectors. + use gstd::{debug, msg, prelude::*}; static mut MESSAGE_LOG: Vec = vec![]; diff --git a/examples/wait-timeout/src/wasm.rs b/examples/wait-timeout/src/wasm.rs index 6bb31bafdbf..7839fd3650a 100644 --- a/examples/wait-timeout/src/wasm.rs +++ b/examples/wait-timeout/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program can timeout itself using [`MessageFuture`](msg::MessageFuture) for a certain +//! number of blocks, or wake the message that is currently in timeout, aswell as use join and +//! select to join multiple futures which are entering a timeout. + use crate::Command; use futures::future; use gstd::{exec, msg, MessageId}; diff --git a/examples/wait/src/wasm.rs b/examples/wait/src/wasm.rs index b6c0a6afafc..c4275fa2b69 100644 --- a/examples/wait/src/wasm.rs +++ b/examples/wait/src/wasm.rs @@ -16,6 +16,11 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program contains a state, which starts at 0, every time it gets incremented, and then the +//! program waits, when it reaches 2, it wakes the two waiting messages that started on states 0 +//! and 1, and the messages now have state 3, where they send a message to the source containing +//! their message id as the payload. + // for panic/oom handlers extern crate gstd; diff --git a/examples/wait_wake/src/wasm.rs b/examples/wait_wake/src/wasm.rs index a4cd16f8ed2..a573a3ff7e6 100644 --- a/examples/wait_wake/src/wasm.rs +++ b/examples/wait_wake/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program can be asked to wait a message, after putting it into a map, or wake a message +//! that is currently in the map. After being woken, the message will be removed from the map and +//! it will send a reply. + use crate::Request; use gstd::{collections::BTreeMap, exec, msg, prelude::*, MessageId}; diff --git a/examples/waiter/src/wasm.rs b/examples/waiter/src/wasm.rs index 56e125a9f39..7b0e29d45c4 100644 --- a/examples/waiter/src/wasm.rs +++ b/examples/waiter/src/wasm.rs @@ -16,6 +16,10 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This contract receives a command, and uses it to determine what to do. It can wait, send +//! messages and use the MessageFuture to wait, reply and wait, wake messages, and wait for mutex +//! and read write locks. + use crate::{ Command, LockContinuation, LockStaticAccessSubcommand, MxLockContinuation, RwLockContinuation, RwLockType, SleepForWaitType, WaitSubcommand, diff --git a/examples/waiting-proxy/src/wasm.rs b/examples/waiting-proxy/src/wasm.rs index 833c5e2a293..bc54f895c39 100644 --- a/examples/waiting-proxy/src/wasm.rs +++ b/examples/waiting-proxy/src/wasm.rs @@ -16,6 +16,9 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +//! This program proxies the input to a predetermined destination, through an async function, +//! awaiting a reply and sending it back to the source of the message. + use gstd::{msg, ActorId}; static mut DESTINATION: ActorId = ActorId::new([0u8; 32]); From 2c8ea7d5ee335b0957dae1a8cdb605aa509b1d8e Mon Sep 17 00:00:00 2001 From: mqxf Date: Thu, 30 Nov 2023 16:56:36 +0100 Subject: [PATCH 5/7] Fixed typo --- examples/sys-calls/src/wasm.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/sys-calls/src/wasm.rs b/examples/sys-calls/src/wasm.rs index f73dd52faa4..d24206071f8 100644 --- a/examples/sys-calls/src/wasm.rs +++ b/examples/sys-calls/src/wasm.rs @@ -16,7 +16,7 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -//! This program allows you to send a list of syscalls and other minor fucntions that it should +//! This program allows you to send a list of syscalls and other minor functions that it should //! execute. use crate::Kind; From 0d1e00c769669670bdbc8046c65fd5a32819325a Mon Sep 17 00:00:00 2001 From: mqxf Date: Fri, 1 Dec 2023 11:36:40 +0100 Subject: [PATCH 6/7] Added examples to build docs --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 147ed020b68..4cabb270839 100644 --- a/Makefile +++ b/Makefile @@ -249,7 +249,8 @@ doc: -p gear-core -p gear-core-processor -p gear-lazy-pages -p gear-core-errors \ -p gmeta -p gstd -p gtest -p gear-wasm-builder -p gear-common \ -p pallet-gear -p pallet-gear-gas -p pallet-gear-messenger -p pallet-gear-payment \ - -p pallet-gear-program -p pallet-gear-rpc-runtime-api -p pallet-gear-rpc -p pallet-gear-scheduler -p gsdk + -p pallet-gear-program -p pallet-gear-rpc-runtime-api -p pallet-gear-rpc -p pallet-gear-scheduler -p gsdk \ + -p demo-* @ cp -f images/logo.svg target/doc/rust-logo.svg .PHONY: kill-gear From 1b315dd7b182848eedb5171bc79e4b68c1f9aa3c Mon Sep 17 00:00:00 2001 From: mqxf Date: Wed, 27 Dec 2023 13:31:30 +0100 Subject: [PATCH 7/7] Minor changes --- examples/async-custom-entry/src/wasm.rs | 2 +- examples/async-init/src/wasm.rs | 3 ++- examples/async-tester/src/wasm.rs | 2 +- examples/async/src/wasm.rs | 2 +- 4 files changed, 5 insertions(+), 4 deletions(-) diff --git a/examples/async-custom-entry/src/wasm.rs b/examples/async-custom-entry/src/wasm.rs index c6b11fda280..a7af534536c 100644 --- a/examples/async-custom-entry/src/wasm.rs +++ b/examples/async-custom-entry/src/wasm.rs @@ -17,7 +17,7 @@ // along with this program. If not, see . //! This program demonstrates the use of async `init` entry point, as well as custom entry point -//! functions for `handle_reply` and `handle_signal`, using of `gstd::async_init` and +//! functions for `handle_reply` and `handle_signal`, using `gstd::async_init` and //! `gstd::async_main` macros. //! //! `Init` is async and saves the source of the message it receives. diff --git a/examples/async-init/src/wasm.rs b/examples/async-init/src/wasm.rs index fa4d824c41d..335319eb269 100644 --- a/examples/async-init/src/wasm.rs +++ b/examples/async-init/src/wasm.rs @@ -17,7 +17,8 @@ // along with this program. If not, see . //! This program demonstrates asynchronous execution and how to use macros `gstd::async_init` and -//! `gstd::async_main`. +//! `gstd::async_main`. It uses async to be able to wait for replies to messages it sent during the execution without +//! having to halt the execution and use `handle_reply`. //! //! `Init` is async and gets three addresses in the payload, sends "PING" messages to them and waits for //! at least two replies with any payload ("approvals"). diff --git a/examples/async-tester/src/wasm.rs b/examples/async-tester/src/wasm.rs index c78cd4a4b1e..14c6c886347 100644 --- a/examples/async-tester/src/wasm.rs +++ b/examples/async-tester/src/wasm.rs @@ -16,7 +16,7 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -//! This program demonstrates the use of [`msg`] syscalls from an async environment. +//! This program demonstrates the use of [`gstd::msg`] syscalls from an async environment. //! //! `Handle` is async and gets a [`Kind`] in the payload, executing a syscall based on the `Kind`, //! and sending a message back to the source with the payload "PONG". diff --git a/examples/async/src/wasm.rs b/examples/async/src/wasm.rs index 946e7ef71e9..0fd37108e4e 100644 --- a/examples/async/src/wasm.rs +++ b/examples/async/src/wasm.rs @@ -27,7 +27,7 @@ //! that can be executed: [`Common`] and [`Mutex`]. //! //! [`Common`] sends three async messages to the ping program, with the payload "PING", -//! awaits the reply and asserts that the reply is "PONG". +//! asynchronously awaits the reply and asserts that the reply is "PONG". //! //! [`Mutex`] asynchronously locks the mutex, awaiting it, sends a message back to the //! source of the current message, containing the current message id in the payload, and then