Terminate built apps without running process teardown

[FeodorFitsner]

Problem

A built app whose Python code was still running when the process ended could crash with EXC_BAD_ACCESS, reported by the OS as an application crash even though the app had finished its work.

Python runs on its own thread alongside Flutter. A normal process exit runs __cxa_finalize (DLL_PROCESS_DETACH on Windows), destroying the C++ statics inside every loaded C extension module while that thread is still executing inside one of them:

Thread 0:  -[NSApplication terminate:] -> exit -> __cxa_finalize_ranges
Thread 5:  sp_worker -> ... -> ft2font: pybind11 type_caster<LoadFlags>::load
           far: 0x0 esr: 0x92000006 (Data Abort) byte read Translation fault

Nothing is matplotlib-specific. A second capture of the same crash caught thread 0 inside SkTypefaceCache::~SkTypefaceCache(), Flutter's own Skia static, on the same pass; numpy and Pillow have statics torn down by it too.

Both exit paths were affected:

• Window close (desktop).
• sys.exit() (every native platform), which is the worse of the two. Flet's patched sys.exit (flet_exit in python.dart) posts the exit code to Dart and returns rather than raising SystemExit, so the interpreter is fully alive, running on into sp_run_target's return and Py_Finalize(), when Dart's exit() tears the process down. Two concurrent teardowns.

Change

The desktop runners hard-exit: _exit on macOS and Linux, TerminateProcess on Windows. Windows needs the different primitive because _exit() and ExitProcess both still run DLL_PROCESS_DETACH, where the CRT's DllMain runs each DLL's static destructors, which is the thing being avoided.

native_runtime.dart routes the sys.exit path through DartBridge.hardExit, falling back to exit() against a pre-1.9.0 bridge. Exit codes are preserved: terminate: always exits 0 and carries no status, so the macOS hook's _exit(0) is not overriding a requested code; a Python-requested exit does not pass through it.

Bumps serious_python to 4.7.0 and re-pins PYTHON_BUILD_RELEASE_DATE to 20260908, keeping it in sync with serious_python's pythonReleaseDate as that pin's own comment requires. No CPython or Pyodide versions change.

Documented contract

This is a deliberate trade, so it is written down rather than left implicit, in a new How a built app terminates section with pointers from the macOS, Linux and Windows pages:

A built Flet app terminates immediately. Python atexit handlers, __del__ finalizers, C++ static destructors, and buffered writes that have not yet reached the operating system are not guaranteed to run.

Verification

macOS, against the published serious_python 4.7.0 / python-build 20260908 / dart_bridge 1.9.0 (clean flet clean rebuild resolving from pub.dev, no path or git overrides), using the matplotlib playground app whose render loop keeps the interpreter thread hot:

Check	Result
Baseline, before the fix	2 crashes / 6 window closes
Window close, after	0 / 12, then 0 / 10 on the fully published stack
sys.exit(3), after	0 / 5, exit code 3 preserved every run
SharedPreferences durability, window close	survives (0,1,2,3 across runs)
SharedPreferences durability, sys.exit	survives (0,1,2,3 across runs)
Pre-1.9.0 native bridge	builds, runs, falls back to exit()

At the observed baseline rate, twelve clean closes by chance is roughly 0.8%.

The repro only fires with the window frontmost: unfocused, Flutter throttles rendering and the interpreter sits in asyncio.sleep rather than inside a C call, which is why an initial unactivated run showed zero crashes before the fix as well.

Not verified

Linux and Windows. Both are implemented from the same analysis but were not run; I had no host for either. The Windows branch deserves a real check before it is relied on, since it is the one platform where the obvious primitive (_exit) is the wrong answer: confirm ExitProcess still crashes and TerminateProcess does not.

A narrower fallback than it looks. The soft symbol lookup covers an older native libdart_bridge at runtime. It does not cover an older serious_python Dart package, where DartBridge.hardExit does not exist and the template fails to compile.

Chain

1. dart-bridge v1.9.0
2. python-build 20260908
3. serious_python 4.7.0 (flet-dev/serious-python#248)
4. this PR

Summary by Sourcery

Make built applications terminate without running unsafe process teardown while documenting the resulting shutdown guarantees and updating supporting runtime dependencies.

Bug Fixes:

• Prevent built applications from crashing during shutdown when Python execution is still active by bypassing normal process teardown on native platforms.
• Preserve requested exit codes when applications terminate through Python's sys.exit().
• Avoid syncing generated build and dependency directories into documentation assets and safely replace read-only copied files.

Enhancements:

• Document the immediate termination behavior of built apps, including cleanup and buffered-write guarantees, and provide guidance for explicit cleanup before exit.

Build:

• Upgrade built app templates to serious_python 4.7.0 and pin the Python build release to 20260908.

Documentation:

• Add termination behavior guidance to the publishing documentation and platform-specific build pages.

Tests:

• Simplify file-removal error tests by removing obsolete Python-version parameterization.

Chores:

• Update the web manifest description.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[cloudflare-workers-and-pages]

Deploying flet-website-v2 with    Cloudflare Pages

Latest commit:	d2b9f18
Status:	✅  Deploy successful!
Preview URL:	https://aa20e5ba.flet-website-v2.pages.dev
Branch Preview URL:	https://hard-exit.flet-website-v2.pages.dev

View logs