diff --git a/documentation/docs/.pages b/documentation/docs/.pages index 2b9e64caa..3786085c2 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 b1923fb52..87012f417 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 000000000..950adb541 --- /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 000000000..bfc4bb4aa --- /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 184791bd4..05636922b 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}"); } ```