From 47b188ec22bbf7f9aba2a9893f0f039c2d26ff63 Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Wed, 2 Aug 2023 14:14:59 -0700 Subject: [PATCH] Mention that the widget tree is not disposed on exit (#131637) --- packages/flutter/lib/src/widgets/binding.dart | 14 ++++++++++++++ packages/flutter/lib/src/widgets/framework.dart | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/packages/flutter/lib/src/widgets/binding.dart b/packages/flutter/lib/src/widgets/binding.dart index 7c8bf3b8df2..900d34fe772 100644 --- a/packages/flutter/lib/src/widgets/binding.dart +++ b/packages/flutter/lib/src/widgets/binding.dart @@ -1152,6 +1152,20 @@ mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureB /// /// Initializes the binding using [WidgetsFlutterBinding] if necessary. /// +/// ## Application shutdown +/// +/// This widget tree is not torn down when the application shuts down, because +/// there is no way to predict when that will happen. For example, a user could +/// physically remove power from their device, or the application could crash +/// unexpectedly, or the malware on the device could forcibly terminate the +/// process. +/// +/// Applications are responsible for ensuring that they are well-behaved +/// even in the face of a rapid unscheduled termination. +/// +/// To artificially cause the entire widget tree to be disposed, consider +/// calling [runApp] with a widget such as [SizedBox.shrink]. +/// /// See also: /// /// * [WidgetsBinding.attachRootWidget], which creates the root widget for the diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 8628b57ba4a..abd202dd943 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -1238,6 +1238,20 @@ abstract class State with Diagnosticable { /// Implementations of this method should end with a call to the inherited /// method, as in `super.dispose()`. /// + /// ## Application shutdown + /// + /// This method is _not_ invoked when the application shuts down, because + /// there is no way to predict when that will happen. For example, a user's + /// battery could catch fire, or the user could drop the device into a + /// swimming pool, or the operating system could unilaterally terminate the + /// application process due to memory pressure. + /// + /// Applications are responsible for ensuring that they are well-behaved + /// even in the face of a rapid unscheduled termination. + /// + /// To artificially cause the entire widget tree to be disposed, consider + /// calling [runApp] with a widget such as [SizedBox.shrink]. + /// /// See also: /// /// * [deactivate], which is called prior to [dispose].