Clarified the reason for adding the deleteSingleton method to LLSingleton....

Clarified the reason for adding the deleteSingleton method to LLSingleton. Added a simple unit test to verify the functionality of the deleteSingleton method.

indra/llcommon/CMakeLists.txt

@@ -319,6 +319,7 @@ if (LL_TESTS)
   LL_ADD_INTEGRATION_TEST(llrand "" "${test_libs}")
   LL_ADD_INTEGRATION_TEST(llsdserialize "" "${test_libs}"
                           "${PYTHON_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/setpython.py")
+  LL_ADD_INTEGRATION_TEST(llsingleton "" "${test_libs}")                          
   LL_ADD_INTEGRATION_TEST(llstring "" "${test_libs}")
   LL_ADD_INTEGRATION_TEST(lltreeiterators "" "${test_libs}")
   LL_ADD_INTEGRATION_TEST(lluri "" "${test_libs}")

indra/llcommon/llsingleton.h

@@ -114,8 +114,7 @@ class LLSingleton : private boost::noncopyable
 
 		~SingletonInstanceData()
 		{
-			SingletonInstanceData& data = getData();
-			if (data.mInitState != DELETED)
+			if (mInitState != DELETED)
 			{
 				deleteSingleton();
 			}
@@ -130,7 +129,26 @@ class LLSingleton : private boost::noncopyable
 		data.mInitState = DELETED;
 	}
 
-	// Can be used to control when the singleton is deleted.  Not normally needed.
+	/**
+	 * @brief Immediately delete the singleton.
+	 *
+	 * A subsequent call to LLProxy::getInstance() will construct a new
+	 * instance of the class.
+	 *
+	 * LLSingletons are normally destroyed after main() has exited and the C++
+	 * runtime is cleaning up statically-constructed objects. Some classes
+	 * derived from LLSingleton have objects that are part of a runtime system
+	 * that is terminated before main() exits. Calling the destructor of those
+	 * objects after the termination of their respective systems can cause
+	 * crashes and other problems during termination of the project. Using this
+	 * method to destroy the singleton early can prevent these crashes.
+	 *
+	 * An example where this is needed is for a LLSingleton that has an APR
+	 * object as a member and make APR calls on destruction. The APR system is
+	 * shut down explicitly before main() exits. This causes a crash on exit.
+	 * Using this method before the call to apr_terminate() and NOT calling
+	 * getInstance() again will prevent the crash.
+	 */
 	static void deleteSingleton()
 	{
 		delete getData().mSingletonInstance;

indra/llcommon/tests/llsingleton_test.cpp

+/** 
+ * @file llprocessor_test.cpp
+ * @date 2010-06-01
+ *
+ * $LicenseInfo:firstyear=2010&license=viewerlgpl$
+ * Second Life Viewer Source Code
+ * Copyright (C) 2010, Linden Research, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation;
+ * version 2.1 of the License only.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
+ * $/LicenseInfo$
+ */
+
+#include "linden_common.h"
+
+#include "llsingleton.h"
+#include "../test/lltut.h"
+
+namespace tut
+{
+	struct singleton
+	{
+		// We need a class created with the LLSingleton template to test with.
+		class LLSingletonTest: public LLSingleton<LLSingletonTest>
+		{
+
+		};
+	};
+
+	typedef test_group<singleton> singleton_t;
+	typedef singleton_t::object singleton_object_t;
+	tut::singleton_t tut_singleton("LLSingleton");
+
+	template<> template<>
+	void singleton_object_t::test<1>()
+	{
+
+	}
+	template<> template<>
+	void singleton_object_t::test<2>()
+	{
+		LLSingletonTest* singleton_test = LLSingletonTest::getInstance();
+		ensure(singleton_test);
+	}
+	template<> template<>
+	void singleton_object_t::test<3>()
+	{
+		//Construct the instance
+		LLSingletonTest::getInstance();
+		ensure(LLSingletonTest::instanceExists());
+
+		//Delete the instance
+		LLSingletonTest::deleteSingleton();
+		ensure(LLSingletonTest::destroyed());
+		ensure(!LLSingletonTest::instanceExists());
+
+		//Construct it again.
+		LLSingletonTest* singleton_test = LLSingletonTest::getInstance();
+		ensure(singleton_test);
+		ensure(LLSingletonTest::instanceExists());
+	}
+}