Settings.h File Reference

#include <functional>
#include <string>
#include <folly/Range.h>
#include <folly/experimental/settings/SettingsMetadata.h>
#include <folly/experimental/settings/detail/SettingsImpl.h>

Go to the source code of this file.

Classes
class	folly::settings::detail::SettingWrapper< T, TrivialPtr >
struct	folly::settings::detail::TypeIdentity< T >
class	folly::settings::detail::SnapshotSettingWrapper< T >
class	folly::settings::Snapshot

Namespaces
	folly
	—— Concurrent Priority Queue Implementation ——
	folly::settings
	folly::settings::detail

Macros
#define	FOLLY_SETTINGS_DEFINE_LOCAL_FUNC__(_project, _name, _Type, _overloadType)
#define	FOLLY_SETTING_DEFINE(_project, _name, _Type, _def, _desc)
#define	FOLLY_SETTING_DECLARE(_project, _name, _Type)   FOLLY_SETTINGS_DEFINE_LOCAL_FUNC__(_project, _name, _Type, int)
#define	FOLLY_SETTING(_project, _name)   FOLLY_SETTINGS_LOCAL_FUNC__##_project##_##_name(0)

Typedefs
template<class T >
using	folly::settings::detail::TypeIdentityT = typename TypeIdentity< T >::type

Functions
Optional< SettingMetadata >	folly::settings::getSettingsMeta (StringPiece settingName)

Macro Definition Documentation

#define FOLLY_SETTING	(		_project,
			_name
	)		FOLLY_SETTINGS_LOCAL_FUNC__##_project##_##_name(0)

Accesses a defined setting. Rationale for the macro: 1) Searchability, all settings access is done via FOLLY_SETTING(...) 2) Prevents omitting trailing () by accident, which could lead to bugs like auto value = *FOLLY_SETTING_project_name;, which compiles but dereferences the function pointer instead of the setting itself.

Definition at line 192 of file Settings.h.

Referenced by a_ns::a_func(), b_ns::b_func(), BENCHMARK(), a_ns::getRemote(), a_ns::setRemote(), and TEST().

#define FOLLY_SETTING_DECLARE	(		_project,
			_name,
			_Type
	)		FOLLY_SETTINGS_DEFINE_LOCAL_FUNC__(_project, _name, _Type, int)

Declares a setting that's defined elsewhere.

Definition at line 180 of file Settings.h.

#define FOLLY_SETTING_DEFINE	(		_project,
			_name,
			_Type,
			_def,
			_desc
	)

Value:

/* Fastpath optimization, see notes in FOLLY_SETTINGS_DEFINE_LOCAL_FUNC__.  \
     Aggregate all off these together in a single section for better TLB      \
     and cache locality. */                                                   \
  __attribute__((__section__(".folly.settings.cache")))                       \
      std::atomic<folly::settings::detail::SettingCore<_Type>*>               \
          FOLLY_SETTINGS_CACHE__##_project##_##_name;                         \
  /* Location for the small value cache (if _Type is small and trivial).      \
     Intentionally located right after the pointer cache above to take        \
     advantage of the prefetching */                                          \
  __attribute__((__section__(".folly.settings.cache"))) std::atomic<uint64_t> \
      FOLLY_SETTINGS_TRIVIAL__##_project##_##_name;                           \
  /* Meyers singleton to avoid SIOF */                                        \
  FOLLY_NOINLINE folly::settings::detail::SettingCore<_Type>&                 \
      FOLLY_SETTINGS_FUNC__##_project##_##_name() {                           \
    static folly::Indestructible<folly::settings::detail::SettingCore<_Type>> \
        setting(                                                              \
            folly::settings::SettingMetadata{                                 \
                #_project, #_name, #_Type, typeid(_Type), #_def, _desc},      \
            folly::settings::detail::TypeIdentityT<_Type>{_def},              \
            FOLLY_SETTINGS_TRIVIAL__##_project##_##_name);                    \
    return *setting;                                                          \
  }                                                                           \
  /* Ensure the setting is registered even if not used in program */          \
  auto& FOLLY_SETTINGS_INIT__##_project##_##_name =                           \
      FOLLY_SETTINGS_FUNC__##_project##_##_name();                            \
  FOLLY_SETTINGS_DEFINE_LOCAL_FUNC__(_project, _name, _Type, char)

Defines a setting.

FOLLY_SETTING_DEFINE() can only be placed in a single translation unit and will be checked against accidental collisions.

The setting API can be accessed via FOLLY_SETTING(project, name).<api_func>() and is documented in the Setting class.

All settings for a common namespace; (project, name) must be unique for the whole program. Collisions are verified at runtime on program startup.

Parameters

_project	Project identifier, can only contain [a-zA-Z0-9]
<em>name	setting name within the project, can only contain [_a-zA-Z0-9]. The string "<project></em><name>" must be unique for the whole program.
_Type	setting value type
_def	default value for the setting
_desc	setting documentation

Definition at line 149 of file Settings.h.

#define FOLLY_SETTINGS_DEFINE_LOCAL_FUNC__	(		_project,
			_name,
			_Type,
			_overloadType
	)

Value:

extern std::atomic<folly::settings::detail::SettingCore<_Type>*>            \
      FOLLY_SETTINGS_CACHE__##_project##_##_name;                             \
  extern std::atomic<uint64_t> FOLLY_SETTINGS_TRIVIAL__##_project##_##_name;  \
  folly::settings::detail::SettingCore<_Type>&                                \
      FOLLY_SETTINGS_FUNC__##_project##_##_name();                            \
  FOLLY_ALWAYS_INLINE auto FOLLY_SETTINGS_LOCAL_FUNC__##_project##_##_name(   \
      _overloadType) {                                                        \
    if (!FOLLY_SETTINGS_CACHE__##_project##_##_name.load()) {                 \
      FOLLY_SETTINGS_CACHE__##_project##_##_name.store(                       \
          &FOLLY_SETTINGS_FUNC__##_project##_##_name());                      \
    }                                                                         \
    return folly::settings::detail::                                          \
        SettingWrapper<_Type, &FOLLY_SETTINGS_TRIVIAL__##_project##_##_name>( \
            *FOLLY_SETTINGS_CACHE__##_project##_##_name.load());              \
  }                                                                           \
  /* This is here just to force a semicolon */                                \
  folly::settings::detail::SettingCore<_Type>&                                \
      FOLLY_SETTINGS_FUNC__##_project##_##_name()

Optimization: fast-path on top of the Meyers singleton. Each translation unit gets this code inlined, while the slow path initialization code is not. We check the global pointer which should only be initialized after the Meyers singleton. It's ok for multiple calls to attempt to update the global pointer, as they would be serialized on the Meyer's singleton initialization lock anyway.

Both FOLLY_SETTING_DECLARE and FOLLY_SETTING_DEFINE will provide a copy of this function and we work around ODR by using different overload types.

Requires a trailing semicolon.

Definition at line 106 of file Settings.h.