From 78ed7c3fa7bfeccd91b72e4b84aa3bc5d714966a Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Wed, 14 May 2025 08:50:26 -0700 Subject: [PATCH 1/3] doc: improve our ios perf docs --- src/content/docs/code-push/performance.mdx | 63 ++++++++++++---------- 1 file changed, 34 insertions(+), 29 deletions(-) diff --git a/src/content/docs/code-push/performance.mdx b/src/content/docs/code-push/performance.mdx index ff3fdd53..2269d23d 100644 --- a/src/content/docs/code-push/performance.mdx +++ b/src/content/docs/code-push/performance.mdx @@ -11,23 +11,22 @@ Shorebird uses its own fork of Flutter. Our fork works exactly as Google's does, including passing all the same functionality and performance tests. -Using Shorebird's fork will result in no change in your App relative to -Google's. If you believe there is an unintended change, please let us know and -we'd love to work with you to diagnose. +Using Shorebird's fork should not result in any change in your app. If you ever +see any change, please let us know so we can work with you to diagnose! ### Patching Updating a Flutter app in production is unique to Shorebird's fork. -Updating a Flutter app with a "patch" will result in the app working exactly as -well as it does for a "release", just with new code. +When using Shorebird your app has two different modes of running, un-patched +("release") and patched ("patch"). Both release and patch builds of your app +should function identically to as they would without Shorebird. The only caveat +is on iOS where patched builds can sometimes run slower than release builds due +to iOS restrictions. -However on iOS our patching mechanism is different from all of the other -platforms. This is due to restrictions from the Apple App Store. - -The Apple App Store requires all updates to use an interpreter. An interpreter -is a software program that can run other programs (rather than running the -program directly on the hardware). Interpreters are slow, including ours. +The iOS App Store requires all app update systems (like Shorebird's) to use an +interpreter. An interpreter is a software program that can run other programs +(rather than running the program directly on hardware). Interpreters are slow. To work around the performance limitations of an interpreter, Shorebird's updating system is designed to avoid using the interpreter as much as possible. @@ -38,15 +37,16 @@ the interpreter (slow), and thus leave all un-changed code running on the CPU ### Why iOS patches are sometimes slow -Unfortunately, compilers, including Dart's, tend to make many non-local changes -to a program as a result of a local change. - -This means that when you change one part of your program, sometimes as a result -Dart might change how it builds an entirely separate part of your program. +Most of the time when you make a change to a part of your program, only that +part of the program is changed. However sometimes small changes to one part of +the program can produce large changes in (seemingly) unrelated parts. -Imagine you have a part of your program: +This is due to how compilers (programs that turn source code into machine code) +optimize their output. Dart's compiler uses several tricks to optimize programs +including "type flow analysis" and "inlining", both of which can cause these +unexpected non-local changes. -before.dart +As an example, imagine you have a part of your program: ``` bool isEven(T value) => value?.isEven ?? false; @@ -68,6 +68,7 @@ void foo(int x) { + void bar(int? x) { + print(isEven(x)); + } +``` In that example, `isEven` and `foo` didn't change. So you would expect Shorebird should be able to run both of those on the CPU (not have to use an interpreter). @@ -88,16 +89,20 @@ your application to "un-link" and run in the interpreter. Unfortunately there is currently no good way to predict if a patch will cause a performance change to your application. -The good news is that this behavior is relatively rare. 9 out of 10 patches -exhibit no difference after patching and when performance impacting changes -occur, Shorebird's tooling and console will warn you. The bad news is that -predicting when a change will trigger the Dart compiler to cause non-local -changes to your program is very difficult. +The good news is that this behavior is relatively rare. 9 out of 10 patches do +not run into unexpected non-local changes like this and exhibit no difference +after patching. Furthermore, when performance impacting changes occur, +Shorebird's tooling and console will warn you. The bad news is that predicting +when a change will trigger the Dart compiler to cause non-local changes to your +program is very difficult. -When these non-local changes occur, the best thing to do is just try to make the -diff smaller and patch again. For many kinds of patches the performance -difference will be either not noticeable, or worth the trade-off as a stop-gap -between now and when a user can update from the stores. +When these non-local changes occur, the best recommendation we have at this time +is to try to make a new, smaller diff, and patch again. -We have several ideas and will continue to improve this behavior in the future. -``` +For the vast majority of patches there is no performance difference at all. For +those which do see a difference, sometimes that difference may still be worth +the trade-off as a stop-gap between now and when a user can get an update via +the App Store. + +We have several approaches to explore to remove this limitation on iOS and +intend to continue to improve this behavior in the future. From 44c77b96fe9e4bd462e43e4f75e9cb8dc1701c85 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Wed, 14 May 2025 09:06:08 -0700 Subject: [PATCH 2/3] chore: add link to app store guidelines --- src/content/docs/code-push/performance.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/content/docs/code-push/performance.mdx b/src/content/docs/code-push/performance.mdx index 2269d23d..6ff730dc 100644 --- a/src/content/docs/code-push/performance.mdx +++ b/src/content/docs/code-push/performance.mdx @@ -24,9 +24,11 @@ should function identically to as they would without Shorebird. The only caveat is on iOS where patched builds can sometimes run slower than release builds due to iOS restrictions. -The iOS App Store requires all app update systems (like Shorebird's) to use an -interpreter. An interpreter is a software program that can run other programs -(rather than running the program directly on hardware). Interpreters are slow. +The iOS App Store +[requires](https://docs.shorebird.dev/faq/#does-shorebird-comply-with-app-store-guidelines) +all app update systems (like Shorebird's) to use an interpreter. An interpreter +is a software program that can run other programs (rather than running the +program directly on hardware). Interpreters are slow. To work around the performance limitations of an interpreter, Shorebird's updating system is designed to avoid using the interpreter as much as possible. From d4ec35e4db1c576801c93d52c0463c6037896af1 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Wed, 14 May 2025 09:07:42 -0700 Subject: [PATCH 3/3] chore: remove parenthetical --- src/content/docs/code-push/performance.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/code-push/performance.mdx b/src/content/docs/code-push/performance.mdx index 6ff730dc..8d310069 100644 --- a/src/content/docs/code-push/performance.mdx +++ b/src/content/docs/code-push/performance.mdx @@ -27,8 +27,8 @@ to iOS restrictions. The iOS App Store [requires](https://docs.shorebird.dev/faq/#does-shorebird-comply-with-app-store-guidelines) all app update systems (like Shorebird's) to use an interpreter. An interpreter -is a software program that can run other programs (rather than running the -program directly on hardware). Interpreters are slow. +is a software program that can run other programs rather than running the +program directly on hardware. Interpreters are slow. To work around the performance limitations of an interpreter, Shorebird's updating system is designed to avoid using the interpreter as much as possible.