When need to use `ManualReply `?

zshuaibin · May 22, 2022, 7:26am

I was following the sample code of rust-profile，i was confused by using ManualReply.

I’ve checked the docs here：
query in ic_cdk_macros - Rust (docs.rs)

so，when need to use ManualReply?

Thank you ~~

AdamS · May 23, 2022, 2:20pm

In the Rust abstraction over the system interface, functions take parameters and produce return values. In the system interface, functions are () -> (), take input by calling ic0.msg_arg_data_*, and produce output by calling ic0.reply. Sometimes these two models of the world conflict.

The function you have posted is one that ‘returns’ Profile in Candid-encoded form. The convenient abstraction would be to return the Profile struct from the function - except Profile contains owned non-Copy data. To return it by value would require cloning it, and there is no lifetime that it could be returned under by reference because it is obtained through thread_local!. The canister would like to not waste cycles with an allocation (allocations are cheap, but it’s an example for when your operation isn’t cheap).

But ownership and lifetimes are irrelevant to the underlying operation - it’s just getting serialized and passed to ic0.reply, which does not require ownership. If you could just ‘return’ your data that way, there are no lifetime problems, and you can pass it to the function by reference just fine. Thus, the manual_reply = true flag on the export macros allows you to reply yourself to skip the entire problem. (This is necessary because otherwise the export macro would call ic0.reply itself, and calling ic0.reply twice traps.)

ManualReply is an abstraction over manually calling ic0.reply. It is a struct that contains no data - it only exists to provide CandidType::ty, so that declaring it as a return type allows you to still auto-generate Candid bindings. When you construct it with parameters, it immediately calls ic0.reply regardless of whether it’s returned or not. Saying

return ManualReply::one(Some(p));

is equivalent to saying

call::reply((Some(p),));
return;

except that declaring it as your return type ensures you cannot accidentally return a value without actually exiting the function. Use of this type is not required when using manual_reply = true - you can use ic_cdk::api::call::reply if you want to.

paulyoung · May 26, 2022, 10:58pm

I hadn’t seen Adam’s reply but came across this motivating example and quickly understood why it’s needed:

github.com

dfinity/examples/blob/8381ca44a172e5aeed7afdf82261c7f3233aac58/rust/dip721-nft-container/src/http.rs#L33-L40

      
        
            // This could reply with a lot of data. To return this data from the function would require it to be cloned,
            // because the thread_local! closure prevents us from returning data borrowed from inside it.
            // Luckily, it doesn't actually get returned from the exported WASM function, that's just an abstraction. 
            // What happens is it gets fed to call::reply, and we can do that explicitly to save the cost of cloning the data.
            // #[query] calls call::reply unconditionally, and calling it twice would trap, so we use #[export_name] directly.
            // This requires duplicating the rest of the abstraction #[query] provides for us, like setting up the panic handler with
            // ic_cdk::setup() and fetching the function parameters via call::arg_data.
            // cdk 0.5 makes this unnecessary, but it has not been released at the time of writing this example.

flyq · October 27, 2022, 8:57am

Very good example, just that I had a problem after looking closely at the comments:

Why do you say cdk 0.5 makes this unnecessary?
Why are headers: HashMap<String, String> not headers: Vec<(String, String)>

github.com

dfinity/examples/blob/master/rust/dip721-nft-container/src/http.rs#L22


      
          use serde::{Deserialize, Serialize};
          use serde_cbor::Serializer;
          use sha2::{Digest, Sha256};
          
          
use crate::{MetadataPurpose, MetadataVal, STATE};
          
          
#[derive(CandidType, Deserialize)]
          struct HttpRequest {
              method: String,
              url: String,
              headers: HashMap<String, String>,
              body: Vec<u8>,
          }
          
          
#[derive(CandidType)]
          struct HttpResponse<'a> {
              status_code: u16,
              headers: HashMap<&'a str, Cow<'a, str>>,
              body: Cow<'a, [u8]>,
          }

paulyoung · October 27, 2022, 3:40pm

I think that’s referring to ic::cdk_setup, call::arg_data, and call::reply.

I think I only added the macro, changed the type signature to include ManualReply and return value to ManualReply::one.
I think because their Candid representation is the same.

Related:

Can you please support the data structure required to respond to http requests? · Issue #328 · dfinity/cdk-rs · GitHub

Topic		Replies	Views
Rust ic_cdk: Minimal example of passing argument to `main::install_code` and decoding inside the target canister Rust	7	797	October 25, 2022
Thread 'tests::save_candid' panicked at 'Cannot use Func directly Rust	3	304	July 21, 2023
Guard functions should not be allowed in init, pre_upgrade, and post_upgrade Developers	1	351	July 27, 2023
Please add examples to the code comments on ic_cdk functions in all the modules Rust	7	665	July 9, 2024
Automatically generate candid from rust sources Developers	68	5416	November 6, 2023

When need to use `ManualReply `?

Related topics