Document the dlclose/thread locals with non-trivial destructors problem.
Bug: https://github.com/android-ndk/ndk/issues/360
Test: N/A
Change-Id: I964a6c9abd1ae65d74c6aee1c842b2f3d24b5556
diff --git a/android-changes-for-ndk-developers.md b/android-changes-for-ndk-developers.md
index c301857..0620d9e 100644
--- a/android-changes-for-ndk-developers.md
+++ b/android-changes-for-ndk-developers.md
@@ -376,3 +376,22 @@
```
enables logging of all errors and dlopen calls
+
+## dlclose interacts badly with thread local variables with non-trivial destructors
+
+Android allows `dlclose` to unload a library even if there are still
+thread-local variables with non-trivial destructors. This leads to
+crashes when a thread exits and attempts to call the destructor, the
+code for which has been unloaded (as in [issue 360]).
+
+[issue 360]: https://github.com/android-ndk/ndk/issues/360
+
+Not calling `dlclose` or ensuring that your library has `RTLD_NODELETE`
+set (so that calls to `dlclose` don't actually unload the library)
+are possible workarounds.
+
+| | Pre-M | M+ |
+| ----------------- | -------------------------- | ------- |
+| No workaround | Works for static STL | Broken |
+| `-Wl,-z,nodelete` | Works for static STL | Works |
+| No `dlclose` | Works | Works |