improve documentation of custom singleton creation through an example

Summary:
improve documentation of custom singleton creation through an example
(from fbcode SIOF thread suggestion)

Reviewed By: yfeldblum

Differential Revision: D4053322

fbshipit-source-id: e9c2ef3d1ef43d52c0bf0a601d94c017047a23a3

diff --git a/folly/Singleton.h b/folly/Singleton.h
index c4640aff40d5b4e41b54f37302ce1e5284e7bed5..126efc97f7f117333f14703e0dc09826a1bfc7dd 100644 (file)
--- a/folly/Singleton.h
+++ b/folly/Singleton.h
@@ -71,6 +71,15 @@
 // Where create and destroy are functions, Singleton<T>::CreateFunc
 // Singleton<T>::TeardownFunc.
 //
+// For example, if you need to pass arguments to your class's constructor:
+//   class X {
+//    public:
+//      X(int a1, std::string a2);
+//    // ...
+//   }
+// Make your singleton like this:
+//   folly::Singleton<X> singleton_x([]() { return new X(42, "foo"); });
+//
 // The above examples detail a situation where an expensive singleton is loaded
 // on-demand (thus only if needed).  However if there is an expensive singleton
 // that will likely be needed, and initialization takes a potentially long time,

diff --git a/folly/test/SingletonTest.cpp b/folly/test/SingletonTest.cpp
index 620dbd11e6602fa14a5c3fd510ee814f7f9ee3e6..fe579484b7380f5099bbd91fe97b98fd39908aba 100644 (file)
--- a/folly/test/SingletonTest.cpp
+++ b/folly/test/SingletonTest.cpp
@@ -610,3 +610,25 @@ TEST(Singleton, DoubleRegistrationLogging) {
   EXPECT_EQ(SIGABRT, res.killSignal());
   EXPECT_THAT(err, testing::StartsWith("Double registration of singletons"));
 }
+
+// Singleton using a non default constructor test/example:
+struct X {
+  X() : X(-1, "unset") {}
+  X(int a1, std::string a2) : a1(a1), a2(a2) {
+    LOG(INFO) << "X(" << a1 << "," << a2 << ")";
+  }
+  const int a1;
+  const std::string a2;
+};
+
+folly::Singleton<X> singleton_x([]() { return new X(42, "foo"); });
+
+TEST(Singleton, CustomCreator) {
+  X x1;
+  std::shared_ptr<X> x2p = singleton_x.try_get();
+  EXPECT_NE(nullptr, x2p);
+  EXPECT_NE(x1.a1, x2p->a1);
+  EXPECT_NE(x1.a2, x2p->a2);
+  EXPECT_EQ(42, x2p->a1);
+  EXPECT_EQ(std::string("foo"), x2p->a2);
+}