folly::SingletonVault Class Reference

#include <Singleton.h>

Classes
struct	ScopedExpunger

Public Types
enum	Type { Type::Strict, Type::Relaxed }
typedef std::function< void(void *)>	TeardownFunc
typedef std::function< void *(void)>	CreateFunc
typedef std::string(*	StackTraceGetterPtr) ()

Public Member Functions
	SingletonVault (Type type=defaultVaultType())
	~SingletonVault ()
void	registerSingleton (detail::SingletonHolderBase *entry)
void	addEagerInitSingleton (detail::SingletonHolderBase *entry)
void	registrationComplete ()
void	doEagerInit ()
void	doEagerInitVia (Executor &exe, folly::Baton<> *done=nullptr)
void	destroyInstances ()
void	reenableInstances ()
size_t	registeredSingletonCount () const
bool	eagerInitComplete () const
size_t	livingSingletonCount () const
void	setType (Type type)

Static Public Member Functions
static Type	defaultVaultType ()
static SingletonVault *	singleton ()
template<typename VaultTag = detail::DefaultTag>
static SingletonVault *	singleton ()
static std::atomic< StackTraceGetterPtr > &	stackTraceGetter ()

Private Types
typedef std::unordered_map< detail::TypeDescriptor, detail::SingletonHolderBase *, detail::TypeDescriptorHasher >	SingletonMap

Static Private Member Functions
static void	scheduleDestroyInstances ()

Private Attributes
Synchronized< SingletonMap, SharedMutexSuppressTSAN >	singletons_
Synchronized< std::unordered_set< detail::SingletonHolderBase * >, SharedMutexSuppressTSAN >	eagerInitSingletons_
Synchronized< std::vector< detail::TypeDescriptor >, SharedMutexSuppressTSAN >	creationOrder_
Synchronized< detail::SingletonVaultState, SharedMutexReadPriority >	state_
Type	type_

Friends
template<typename T >
struct	detail::SingletonHolder

Detailed Description

Definition at line 375 of file Singleton.h.

Member Typedef Documentation

typedef std::function<void*(void)> folly::SingletonVault::CreateFunc

Definition at line 415 of file Singleton.h.

typedef std::unordered_map< detail::TypeDescriptor, detail::SingletonHolderBase*, detail::TypeDescriptorHasher> folly::SingletonVault::SingletonMap

private

Definition at line 541 of file Singleton.h.

typedef std::string(* folly::SingletonVault::StackTraceGetterPtr) ()

Definition at line 508 of file Singleton.h.

typedef std::function<void(void*)> folly::SingletonVault::TeardownFunc

Definition at line 414 of file Singleton.h.

Member Enumeration Documentation

enum folly::SingletonVault::Type

strong

Enumerator
Strict
Relaxed

Definition at line 377 of file Singleton.h.

                  {
    Strict, // Singletons can't be created before registrationComplete()
    Relaxed, // Singletons can be created before registrationComplete()
  };

Constructor & Destructor Documentation

folly::SingletonVault::SingletonVault ( Type  type = defaultVaultType() )

inlineexplicit

Definition at line 409 of file Singleton.h.

: type_(type) {}

folly::SingletonVault::~SingletonVault

(

)

Definition at line 221 of file Singleton.cpp.

                                {
  destroyInstances();
}

Member Function Documentation

void folly::SingletonVault::addEagerInitSingleton

(

detail::SingletonHolderBase *

entry

)

Called by Singleton<T>.shouldEagerInit() to ensure the instance is built when doEagerInit[Via] is called; see those methods for more info.

Definition at line 238 of file Singleton.cpp.

References CHECK_THROW, folly::detail::SingletonVaultState::Running, folly::detail::SingletonHolderBase::type(), and UNLIKELY.

                                                                           {
  auto state = state_.rlock();
  state->check(detail::SingletonVaultState::Type::Running);

  if (UNLIKELY(state->registrationComplete)) {
    LOG(ERROR) << "Registering for eager-load after registrationComplete().";
  }

  CHECK_THROW(singletons_.rlock()->count(entry->type()), std::logic_error);

  auto eagerInitSingletons = eagerInitSingletons_.wlock();
  eagerInitSingletons->insert(entry);
}

SingletonVault::Type folly::SingletonVault::defaultVaultType ( )

static

Definition at line 51 of file Singleton.cpp.

References folly::detail::singleton_hs_init_weak().

                                                    {
#if FOLLY_SINGLETON_HAVE_DLSYM
  bool isPython = dlsym(RTLD_DEFAULT, "Py_Main");
  bool isHaskel =
      detail::singleton_hs_init_weak || dlsym(RTLD_DEFAULT, "hs_init");
  bool isJVM = dlsym(RTLD_DEFAULT, "JNI_GetCreatedJavaVMs");
  bool isD = dlsym(RTLD_DEFAULT, "_d_run_main");

  return isPython || isHaskel || isJVM || isD ? Type::Relaxed : Type::Strict;
#else
  return Type::Relaxed;
#endif
}

void folly::SingletonVault::destroyInstances

(

)

Definition at line 328 of file Singleton.cpp.

References folly::detail::SingletonVaultState::Quiescing.

Referenced by folly::SingletonVault::ScopedExpunger::expunge(), registrationComplete(), scheduleDestroyInstances(), TEST(), and folly::Init::~Init().

                                      {
  auto stateW = state_.wlock();
  if (stateW->state == detail::SingletonVaultState::Type::Quiescing) {
    return;
  }
  stateW->state = detail::SingletonVaultState::Type::Quiescing;

  auto stateR = stateW.moveFromWriteToRead();
  {
    auto singletons = singletons_.rlock();
    auto creationOrder = creationOrder_.rlock();

    CHECK_GE(singletons->size(), creationOrder->size());

    // Release all ReadMostlyMainPtrs at once
    {
      ReadMostlyMainPtrDeleter<> deleter;
      for (auto& singleton_type : *creationOrder) {
        singletons->at(singleton_type)->preDestroyInstance(deleter);
      }
    }

    for (auto type_iter = creationOrder->rbegin();
         type_iter != creationOrder->rend();
         ++type_iter) {
      singletons->at(*type_iter)->destroyInstance();
    }

    for (auto& singleton_type : *creationOrder) {
      auto instance = singletons->at(singleton_type);
      if (!instance->hasLiveInstance()) {
        continue;
      }

      fatalHelper.leakedSingletons_.push_back(instance->type());
    }
  }

  {
    auto creationOrder = creationOrder_.wlock();
    creationOrder->clear();
  }
}

void folly::SingletonVault::doEagerInit

(

)

Initialize all singletons which were marked as eager-initialized (using shouldEagerInit()). No return value. Propagates exceptions from constructors / create functions, as is the usual case when calling for example Singleton<Foo>::get_weak().

Definition at line 276 of file Singleton.cpp.

References folly::detail::SingletonVaultState::Running, single, and UNLIKELY.

                                 {
  {
    auto state = state_.rlock();
    state->check(detail::SingletonVaultState::Type::Running);
    if (UNLIKELY(!state->registrationComplete)) {
      throw std::logic_error("registrationComplete() not yet called");
    }
  }

  auto eagerInitSingletons = eagerInitSingletons_.rlock();
  for (auto* single : *eagerInitSingletons) {
    single->createInstance();
  }
}

void folly::SingletonVault::doEagerInitVia	(	Executor &	exe,
		folly::Baton<> *	done = nullptr
	)

Schedule eager singletons' initializations through the given executor. If baton ptr is not null, its post method is called after all early initialization has completed.

If exceptions are thrown during initialization, this method will still post the baton to indicate completion. The exception will not propagate and future attempts to try_get or get_weak the failed singleton will retry initialization.

Sample usage:

folly::IOThreadPoolExecutor executor(max_concurrency_level); folly::Baton<> done; doEagerInitVia(executor, &done); done.wait(); // or 'try_wait_for', etc.

Definition at line 291 of file Singleton.cpp.

References folly::Executor::add(), folly::Baton< MayBlock, Atom >::post(), folly::detail::SingletonVaultState::Running, SCOPE_EXIT, single, and UNLIKELY.

                                                                     {
  {
    auto state = state_.rlock();
    state->check(detail::SingletonVaultState::Type::Running);
    if (UNLIKELY(!state->registrationComplete)) {
      throw std::logic_error("registrationComplete() not yet called");
    }
  }

  auto eagerInitSingletons = eagerInitSingletons_.rlock();
  auto countdown =
      std::make_shared<std::atomic<size_t>>(eagerInitSingletons->size());
  for (auto* single : *eagerInitSingletons) {
    // countdown is retained by shared_ptr, and will be alive until last lambda
    // is done.  notifyBaton is provided by the caller, and expected to remain
    // present (if it's non-nullptr).  singletonSet can go out of scope but
    // its values, which are SingletonHolderBase pointers, are alive as long as
    // SingletonVault is not being destroyed.
    exe.add([=] {
      // decrement counter and notify if requested, whether initialization
      // was successful, was skipped (already initialized), or exception thrown.
      SCOPE_EXIT {
        if (--(*countdown) == 0) {
          if (done != nullptr) {
            done->post();
          }
        }
      };
      // if initialization is in progress in another thread, don't try to init
      // here.  Otherwise the current thread will block on 'createInstance'.
      if (!single->creationStarted()) {
        single->createInstance();
      }
    });
  }
}

bool folly::SingletonVault::eagerInitComplete

(

)

const

Flips to true if eager initialization was used, and has completed. Never set to true if "doEagerInit()" or "doEagerInitVia" never called.

size_t folly::SingletonVault::livingSingletonCount ( ) const

inline

Definition at line 480 of file Singleton.h.

                                      {
    auto singletons = singletons_.rlock();

    size_t ret = 0;
    for (const auto& p : *singletons) {
      if (p.second->hasLiveInstance()) {
        ++ret;
      }
    }

    return ret;
  }

void folly::SingletonVault::reenableInstances

(

)

Definition at line 372 of file Singleton.cpp.

References folly::detail::SingletonVaultState::Quiescing, and folly::detail::SingletonVaultState::Running.

Referenced by folly::SingletonVault::ScopedExpunger::expunge().

                                       {
  auto state = state_.wlock();

  state->check(detail::SingletonVaultState::Type::Quiescing);

  state->state = detail::SingletonVaultState::Type::Running;
}

size_t folly::SingletonVault::registeredSingletonCount ( ) const

inline

Definition at line 470 of file Singleton.h.

                                          {
    return singletons_.rlock()->size();
  }

void folly::SingletonVault::registerSingleton

(

detail::SingletonHolderBase *

entry

)

Definition at line 225 of file Singleton.cpp.

References CHECK_THROW, folly::detail::SingletonVaultState::Running, folly::detail::SingletonHolderBase::type(), and UNLIKELY.

                                                                       {
  auto state = state_.rlock();
  state->check(detail::SingletonVaultState::Type::Running);

  if (UNLIKELY(state->registrationComplete)) {
    LOG(ERROR) << "Registering singleton after registrationComplete().";
  }

  auto singletons = singletons_.wlock();
  CHECK_THROW(
      singletons->emplace(entry->type(), entry).second, std::logic_error);
}

void folly::SingletonVault::registrationComplete

(

)

Definition at line 252 of file Singleton.cpp.

References destroyInstances(), folly::detail::SingletonVaultState::Running, singleton(), and type_.

Referenced by folly::init().

                                          {
  std::atexit([]() { SingletonVault::singleton()->destroyInstances(); });

  auto state = state_.wlock();
  state->check(detail::SingletonVaultState::Type::Running);

  if (state->registrationComplete) {
    return;
  }

  auto singletons = singletons_.rlock();
  if (type_ == Type::Strict) {
    for (const auto& p : *singletons) {
      if (p.second->hasLiveInstance()) {
        throw std::runtime_error(
            "Singleton " + p.first.name() +
            " created before registration was complete.");
      }
    }
  }

  state->registrationComplete = true;
}

void folly::SingletonVault::scheduleDestroyInstances ( )

staticprivate

Definition at line 380 of file Singleton.cpp.

References __attribute__(), destroyInstances(), folly::symbolizer::getStackTraceSafe(), folly::threadlocal_detail::StaticMeta< Tag, AccessMode >::instance(), testing::kMaxStackTraceDepth, folly::symbolizer::SymbolizePrinter::println(), singleton(), stackTraceGetter(), folly::symbolizer::StringSymbolizePrinter::str(), string, and folly::symbolizer::Symbolizer::symbolize().

Referenced by folly::detail::SingletonHolder< T >::createInstance().

                                              {
  // Add a dependency on folly::ThreadLocal to make sure all its static
  // singletons are initalized first.
  threadlocal_detail::StaticMeta<void, void>::instance();
  std::atexit([] { SingletonVault::singleton()->destroyInstances(); });
}

void folly::SingletonVault::setType ( Type  type )

inline

Definition at line 516 of file Singleton.h.

References type, and type_.

                          {
    type_ = type;
  }

static SingletonVault* folly::SingletonVault::singleton ( )

inlinestatic

Definition at line 495 of file Singleton.h.

Referenced by folly::init(), registrationComplete(), scheduleDestroyInstances(), TEST(), and folly::Init::~Init().

                                     {
    return singleton<>();
  }

template<typename VaultTag = detail::DefaultTag>

static SingletonVault* folly::SingletonVault::singleton ( )

inlinestatic

Definition at line 502 of file Singleton.h.

                                     {
    /* library-local */ static auto vault =
        detail::createGlobal<SingletonVault, VaultTag>();
    return vault;
  }

static std::atomic<StackTraceGetterPtr>& folly::SingletonVault::stackTraceGetter ( )

inlinestatic

Definition at line 510 of file Singleton.h.

Referenced by proxygen::logging_details::getStackTrace(), scheduleDestroyInstances(), folly::detail::singletonPrintDestructionStackTrace(), folly::detail::singletonWarnCreateBeforeRegistrationCompleteAndAbort(), folly::detail::singletonWarnCreateUnregisteredAndAbort(), and folly::detail::singletonWarnLeakyInstantiatingNotRegisteredAndAbort().

                                                            {
    /* library-local */ static auto stackTraceGetterPtr = detail::
        createGlobal<std::atomic<StackTraceGetterPtr>, SingletonVault>();
    return *stackTraceGetterPtr;
  }

Friends And Related Function Documentation

template<typename T >

friend struct detail::SingletonHolder

friend

Definition at line 522 of file Singleton.h.

Member Data Documentation

Synchronized<std::vector<detail::TypeDescriptor>, SharedMutexSuppressTSAN> folly::SingletonVault::creationOrder_

private

Definition at line 552 of file Singleton.h.

Referenced by folly::detail::SingletonHolder< T >::createInstance().

Synchronized< std::unordered_set<detail::SingletonHolderBase*>, SharedMutexSuppressTSAN> folly::SingletonVault::eagerInitSingletons_

private

Definition at line 550 of file Singleton.h.

Synchronized<SingletonMap, SharedMutexSuppressTSAN> folly::SingletonVault::singletons_

private

Definition at line 546 of file Singleton.h.

Synchronized<detail::SingletonVaultState, SharedMutexReadPriority> folly::SingletonVault::state_

private

Definition at line 557 of file Singleton.h.

Referenced by folly::detail::SingletonHolder< T >::createInstance().

Type folly::SingletonVault::type_

private

Definition at line 559 of file Singleton.h.

Referenced by folly::detail::SingletonHolder< T >::createInstance().

---

The documentation for this class was generated from the following files:

• proxygen/folly/folly/Singleton.h
• proxygen/folly/folly/Singleton.cpp