From 1ae45f6209a3ef4fa5193fea16edc6bcae968fcd Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Fri, 31 May 2024 01:41:29 +0900 Subject: [PATCH] Split pages --- documentation/docs/.pages | 4 +- ...writing-code.md => detailed-techniques.md} | 57 +------------------ documentation/docs/graceful-shutdown.md | 41 +++++++++++++ documentation/docs/printing-for-debugging.md | 12 ++++ documentation/docs/state-management.md | 14 ++--- 5 files changed, 63 insertions(+), 65 deletions(-) rename documentation/docs/{writing-code.md => detailed-techniques.md} (58%) create mode 100644 documentation/docs/graceful-shutdown.md create mode 100644 documentation/docs/printing-for-debugging.md diff --git a/documentation/docs/.pages b/documentation/docs/.pages index 2b9e64ca..3786085c 100644 --- a/documentation/docs/.pages +++ b/documentation/docs/.pages @@ -5,8 +5,10 @@ nav: - running-and-building.md - messaging.md - tutorial.md - - writing-code.md + - detailed-techniques.md - state-management.md + - printing-for-debugging.md + - graceful-shutdown.md - configuration.md - frequently-asked-questions.md - contribution.md diff --git a/documentation/docs/writing-code.md b/documentation/docs/detailed-techniques.md similarity index 58% rename from documentation/docs/writing-code.md rename to documentation/docs/detailed-techniques.md index b1923fb5..87012f41 100644 --- a/documentation/docs/writing-code.md +++ b/documentation/docs/detailed-techniques.md @@ -1,4 +1,4 @@ -# Writing Code +# Detailed Techniques ## 🏷️ Signal Details @@ -53,58 +53,3 @@ This applies same to marked Protobuf messages. // responsible for... message OtherData { ... } ``` - -## 🖨️ Printing for Debugging - -You might be used to `println!` macro in Rust. However, using that macro isn't a very good idea in our apps made with Flutter and Rust because `println!` outputs cannot be seen on the web and mobile emulators. - -When writing Rust code in the `hub` crate, you can simply print your debug message with the `debug_print!` macro provided by this framework like below. Once you use this macro, Flutter will take care of the rest. - -```rust title="Rust" -use rinf::debug_print; -debug_print!("My object is {my_object:?}"); -``` - -`debug_print!` is also better than `println!` because it only works in debug mode, resulting in a smaller and cleaner release binary. - -## 🌅 Closing the App Gracefully - -When the Flutter app is closed, the whole `tokio` runtime on the Rust side will be terminated automatically. However, some error messages can appear in the console if the Rust side sends messages to the Dart side even after the Dart VM has stopped. To prevent this, you can call `finalizeRust()` in Dart to terminate all Rust tasks before closing the Flutter app. - -```dart title="lib/main.dart" -import 'dart:ui'; -import 'package:flutter/material.dart'; -import './messages/generated.dart'; -... -class MyApp extends StatefulWidget { - const MyApp({super.key}); - - @override - State createState() => _MyAppState(); -} - -class _MyAppState extends State { - final _appLifecycleListener = AppLifecycleListener( - onExitRequested: () async { - // Terminate Rust tasks before closing the Flutter app. - await finalizeRust(); - return AppExitResponse.exit; - }, - ); - - @override - void dispose() { - _appLifecycleListener.dispose(); - super.dispose(); - } - - @override - Widget build(BuildContext context) { - return MaterialApp( - title: 'Some App', - home: MyHomePage(), - ); - } -} -... -``` diff --git a/documentation/docs/graceful-shutdown.md b/documentation/docs/graceful-shutdown.md new file mode 100644 index 00000000..950adb54 --- /dev/null +++ b/documentation/docs/graceful-shutdown.md @@ -0,0 +1,41 @@ +# Graceful Shutdown + +When the Flutter app is closed, the entire `tokio` runtime on the Rust side will be terminated automatically. However, you might need to run some finalization code in Rust before the app closes. This might involve saving files or disposing of resources. To achieve this, you can call `finalizeRust()` in Dart to terminate all Rust tasks before closing the Flutter app. + +```dart title="lib/main.dart" +import 'dart:ui'; +import 'package:flutter/material.dart'; +import './messages/generated.dart'; +... +class MyApp extends StatefulWidget { + const MyApp({super.key}); + + @override + State createState() => _MyAppState(); +} + +class _MyAppState extends State { + final _appLifecycleListener = AppLifecycleListener( + onExitRequested: () async { + // Terminate Rust tasks before closing the Flutter app. + await finalizeRust(); + return AppExitResponse.exit; + }, + ); + + @override + void dispose() { + _appLifecycleListener.dispose(); + super.dispose(); + } + + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'Some App', + home: MyHomePage(), + ); + } +} +... +``` diff --git a/documentation/docs/printing-for-debugging.md b/documentation/docs/printing-for-debugging.md new file mode 100644 index 00000000..bfc4bb4a --- /dev/null +++ b/documentation/docs/printing-for-debugging.md @@ -0,0 +1,12 @@ +# Printing for Debugging + +You might be used to `println!` macro in Rust. However, using that macro isn't a very good idea in our apps made with Flutter and Rust because `println!` outputs cannot be seen on the web and mobile emulators. + +When writing Rust code in the `hub` crate, you can simply print your debug message with the `debug_print!` macro provided by this framework like below. Once you use this macro, Flutter will take care of the rest. + +```rust title="Rust" +use rinf::debug_print; +debug_print!("My object is {my_object:?}"); +``` + +`debug_print!` is also better than `println!` because it only works in debug mode, resulting in a smaller and cleaner release binary. diff --git a/documentation/docs/state-management.md b/documentation/docs/state-management.md index 184791bd..05636922 100644 --- a/documentation/docs/state-management.md +++ b/documentation/docs/state-management.md @@ -20,9 +20,8 @@ async fn main() { } pub async fn do_something_with_state(data: Arc>>) { - // Get the mutex guard. - let mut vector = data.lock().await; - vector.push(3); + // Mutate the shared variable directly. + VECTOR.lock().await.push(3); } ``` @@ -35,12 +34,11 @@ use tokio::sync::Mutex; static VECTOR: Mutex> = Mutex::const_new(Vec::new()); pub async fn do_something_with_state() { - // Get the mutex guard. - let mut vector = VECTOR.lock().await; + VECTOR.lock().await.push(true); - // Custom logic here. - vector.push(true); - let length = vector.len(); + // Use the global variable by acquiring the guard. + let guard = VECTOR.lock().await; + let length = guard.len(); debug_print!("{length}"); } ```