Commit & document workaround for TLV/TLS & exit terminator issues.

Avoids crashes on exit for multiple libraries on multiple OS.

Will hopefully document with specifics in future.

Note: This means libraries cannot be unloaded/reloaded/closed
      before program exit.

Author: follower

src/crossplatform.cpp

@@ -7,7 +7,39 @@ std::string error_number_as_string;
 
 HANDLE open_library(const char *path) {
 #ifdef IS_UNIX
-    return dlopen(path, RTLD_LAZY);  // TODO: Is RTLD_LAZY the best?
+    //
+    // Note: Experience has shown that multiple platforms/libraries
+    //       have issues with handling dynamically loaded shared
+    //       libraries and Thread Local Variables/Thread Local Storage
+    //       and/or at exit terminators properly.
+    //
+    //       This can result in multiple thread crashes when the
+    //       program exits because the library is no longer loaded
+    //       but pointers to the library clean-up functions still exist.
+    //
+    //       The best workaround found so far is to...just not unload
+    //       a library when it is closed. :/
+    //
+    //       The workaround is implemented via the addition of an
+    //       additional `dlopen()` call which is (by design) never
+    //       matched with a `dlclose()` call. This results in all
+    //       at exit/thread local storage cleanup happening when the
+    //       main thread is exiting.
+    //
+    //       The disadvantage of this workaround is that it means
+    //       it's not possible to "reload" a shared library but
+    //       we can cross that bridge when someone gets to it. :)
+    //
+    //       Additional note: In theory `RTLD_NODELETE` should have
+    //       also worked as a workaround but it led to crashes.
+    //       (Also tried `RTLD_LOCAL` or `RTLD_FIRST` approaches.)
+    //
+    //
+    //       TODO: Document TLV on Mac issue with Library X.
+    //       TODO: Document at exit terminator issue on Linux with Library Y.
+    //
+    dlopen(path, RTLD_LAZY|RTLD_GLOBAL); // Workaround to bump ref-count so library never unloaded.
+    return dlopen(path, RTLD_LAZY|RTLD_GLOBAL|RTLD_NOLOAD);  // TODO: Is RTLD_LAZY the best?
 #else
     return LoadLibrary(path);
 #endif
@@ -25,6 +57,8 @@ const char *open_library_error() {
 
 int close_library(HANDLE handle) {
 #ifdef IS_UNIX
+    // Note: See workaround note in `open_library()` above as to why
+    //       the following line will no longer unload library.
     return dlclose(handle);
 #else
     return FreeLibrary((HMODULE) handle);