diff --git a/packages/flutter/lib/src/widgets/binding.dart b/packages/flutter/lib/src/widgets/binding.dart index 7c8bf3b8df..900d34fe77 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 8628b57ba4..abd202dd94 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].