Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update auction-signals/system-signals.md #73

Merged
merged 2 commits into from
Jul 14, 2023
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions docs/19-auction-signals/system-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,25 @@ hide_table_of_contents: true

In Gear programs, there are three common entry points: `init`, `handle`, and `handle_reply`. The Gear Protocol also introduces the `handle_signal` entry point, which enables the system to communicate with programs and notify them (signal) of events related to the program's messages. Only the system (Gear node runtime) can send signal messages to a program.

The system sends messages to a program if some errors during program execution occurred. For example, a program can panic or run out of gas.
The system sends messages to a program in the event of errors during program execution. For example, a program can panic or run out of gas.

The `gstd` library provides a separate function for reserving gas specifically for system signal messages.
The `gstd` library provides a separate function for reserving gas exclusively for system signal messages.

```rust
exec::system_reserve_gas(1_000_000_000)
.expect("Error during system gas reservation");
```

This cannot be used for sending other regular cross-actor messages. While signals can be used for inter-actor communication, they are not suitable for sending regular cross-actor messages.
The function cannot send other regular cross-actor messages. Although signals allow inter-actor communication, they do not suit the regular cross-actor message sending.

Signal messages use gas that is specifically reserved for them. If no gas has been reserved for system messages, they will be skipped, and the program will not receive them.
Signal messages utilize gas reserved exclusively for them. If there is no reserved gas for system messages, the system skips them, and the program does not receive them.

If gas has been reserved but no system messages occur during the current execution, then this gas returns back from where it was taken. If your program uses asynchronous messages and the `#[gstd::async_main]` macro is used to expand the `handle_signal` entry point, it will free up resources occupied by the program.
If there's reserved gas and no system messages occur during the ongoing execution, the gas will return to its source. When your program uses asynchronous messages and expands the `handle_signal` entry point with the `#[gstd::async_main]` macro, it frees up the resources that the program occupies.

In Gear, using custom async logic involves storing Futures in the program's memory. The execution context of these Futures can occupy a significant amount of memory, especially when dealing with many Futures.
Using custom async logic involves storing Futures in the program's memory in Gear. The execution context of these Futures can occupy a significant amount of memory, especially when dealing with many Futures.

It's important to note that if a program sends a message and waits for a reply, but the reply is unable to be received, it could be due to a lack of gas. For example, if the initial message in the waitlist runs out of gas or the gas amount is insufficient, the reply cannot be received.
**Note:** If a program sends a message and waits for a reply but cannot receive it, it may be due to insufficient gas. For instance, when the initial message in the waitlist runs out of gas or the gas amount is inadequate, the program cannot receive a reply.
shamilsan marked this conversation as resolved.
Show resolved Hide resolved

To handle signals in your program, you can define your own `my_handle_signal` entry point and write custom logic for it. In the next section, we'll see an example of how to write this function in the auction contract.
To handle signals in your program, you can define your own `my_handle_signal` entry point and write custom logic for your program.

In the next section, we'll explore how to write the `my_handle_signal` function in the auction contract.