bslmf_detectnestedtrait Component

Provide a facility for defining traits and detecting legacy traits. More...

Namespaces
namespace	bslmf

Detailed Description

Outline

Purpose
Classes
Description

Purpose:: Provide a facility for defining traits and detecting legacy traits.

Classes:

bslmf::DetectNestedTrait

meta-function to test a nested trait

See also:: Component bslmf_nestedtraitdeclaration

Description:: This component defines a meta-function, bslmf::DetectNestedTrait, that facilitates the creation of traits that can be associated with a type using the nested trait mechanism in bslmf_declarenestedtrait. Such traits are referred to as "nested traits" because their association with a type is embedded within the type's definition. bslmf::DetectNestedTrait and can also be used to detect traits created using older legacy traits definitions mechanisms used at Bloomberg.

Please note:

The use of bslmf::DetectNestedTrait to detect traits is deprecated. Clients should detect traits using the C++11 idiom (see Nested Trait Idiom vs. C++11 Trait Idiom below)
Clients are encouraged to use a C++11 idiom for defining traits. However, authors of traits who want trait users to be able to take advantage of bslmf_nestedtraitdeclaration must define traits that inherit from bslmf::DetectNestedTrait (see Writing a User-Defined Trait below).

Nested Trait Idiom vs. C++11 Trait Idiom:: BDE supports two idioms for defining traits and associating them with types. The older idiom uses bslmf::DetectNestedTrait to define traits, and the BSLMF_NESTED_TRAIT_DECLARATION* macros to associate traits with types. This idiom is called the "nested trait" idiom.

: The newer idiom is familiar to users of C++11 traits, and is referred to here as the "C++11 trait" idiom. In the C++11 trait idiom, a trait is a template that derives its truth value from bsl::true_type or bsl::false_type, and is associated with a type by providing a specialization of the trait for the associated type.

For example, a minimal C++11 trait, abcd::C11Trait, could be defined as:

  namespace abcd {

  template <class t_TYPE>
  struct C11Trait : bsl::false_type {
  };

  }  // close namespace abcd

abcd::C11Trait would then be associated with a class, xyza::SomeClass, by specializing the trait for that class:

  namespace xyza {

  class SomeClass {
      // The definition of 'SomeClass' does not affect the trait mechanism.

      // ...
  };

  }  // close namespace xyza

  namespace abcd {

  template <>
  struct C11Trait<xyza::SomeClass> : bsl::true_type {
  };

  }  // close namespace abcd

Note that the specialization is defined in the same namespace as the original trait.

Both idioms detect the association of a trait with a class in the same way: by inspecting the trait's value member.

  assert(true  == abcd::C11Trait<xyza::SomeClass>::value);
  assert(false == abcd::C11Trait<xyza::Foo>::value);
  assert(true  == abcd::BarTrait<xyza::Foo>::value);
  assert(false == abcd::BarTrait<xyza::SomeClass>::value);

The C++11 trait idiom is the standard idiom for new code in BDE.

Writing a User-Defined Trait:: On systems that do not require compatibility with the nested trait idiom, new traits should be written according to the C++11 trait idiom.

: On systems that support the nested trait idiom, any new user-defined trait should derive its truth value from bslmf::DetectNestedTrait following the Curiously Recurring Template Pattern. This will allow the trait to be detected by directly inspecting the trait's value member, regardless of whether the trait is associated with a type through the nested trait idiom or through the C++11 trait idiom.

Therefore, the simplest maximally-compatible trait would look like this:

  template <class t_TYPE>
  struct MyTrait : bslmf::DetectNestedTrait<t_TYPE, MyTrait>::type {};

A trait having more complex default logic could derive from bsl::integral_constant using the value member of bslmf::DetectNestedTrait, such as:

  template <class t_TYPE>
  struct ComplexTrait : bsl::integral_constant<bool,
                       bslmf::DetectNestedTrait<t_TYPE, ComplexTrait>::value
                       || SomeOtherTrait<t_TYPE>::value> {
  };

These are the only recommended uses of bslmf::DetectNestedTrait<t_TYPE, t_TRAIT>type and bslmf::DetectNestedTrait<t_TYPE, t_TRAIT>value.

Detecting Legacy Traits:: If a trait, t_TRAIT, has been associated with a type, t_TYPE, using one of the BSLMF_NESTED_TRAIT_DECLARATION* macros then bslmf::DetectNestedTrait<t_TYPE, t_TRAIT> derives from bsl::true_type. Otherwise, bslmf::DetectNestedTrait<t_TYPE, t_TRAIT> derives from bsl::false_type.

Therefore, if a trait abcd::BarTrait has been associated with a class xyza::Foo in the following way:

  namespace xyza {

  class Foo {
      // ... various implementation details ...

    public:
      // TRAITS
      BSLMF_NESTED_TRAIT_DECLARATION(Foo, abcd::BarTrait);

      // ... the rest of the public interface ...
  };

  }  // close namespace xyza

then bslmf::DetectNestedTrait<t_TYPE, t_TRAIT>value will evaluate to true and bslmf::DetectNestedTrait<t_TYPE, t_TRAIT>type will be bsl::true_type.

Usage:: This section illustrates intended use of this component.

Example 1: Defining a Custom Trait:: When writing generic infrastructure code, we often need to choose among multiple code paths based on the capabilities of the types on which we are operating. If those capabilities are reflected in a type's public interface, we may be able to use techniques such as SFINAE to choose the appropriate code path. However, SFINAE cannot detect all of a type's capabilities. In particular, SFINAE cannot detect constructors, memory allocation, thread-safety characteristics, and so on. Functions that depend on these capabilities must use another technique to determine the correct code path to use for a given type. We can solve this sort of problem by associating types with custom traits that indicate what capabilities are provided by a given type.

First, in package abcd, define a trait, RequiresLockTrait, that indicates that a type's methods must not be called unless a known lock it first acquired:

  namespace abcd {

  template <class t_TYPE>
  struct RequiresLockTrait :
                  bslmf::DetectNestedTrait<t_TYPE, RequiresLockTrait>::type {
  };

  } // close package namespace

Notice that RequiresLockTrait derives from bslmf::DetectNestedTrait<t_TYPE, RequiresLockTrait>type using the curiously recurring template pattern.

Then, in package xyza, we declare a type, DoesNotRequireALockType, that can be used without acquiring the lock:

  namespace xyza {

  class DoesNotRequireLockType {
      // ...

    public:
      // CREATORS
      DoesNotRequireLockType();
          // ...
  };

Next, we declare a type, RequiresLockTypeA, that does require the lock. We use the BSLMF_NESTED_TRAIT_DECLARATION macro to associate the type with the abcd::RequiresLockTrait trait:

  class RequiresLockTypeA {
      // ...

    public:
      // TRAITS
      BSLMF_NESTED_TRAIT_DECLARATION(RequiresLockTypeA,
                                     abcd::RequiresLockTrait);

      // CREATORS
      RequiresLockTypeA();
          // ...

  };

Notice that the macro declaration is performed within the scope of the class declaration, and must be done with public scope.

Then, we declare a templatized container type, Container, that is parameterized on some ELEMENT type. If ELEMENT requires a lock, then a Container of ELEMENTs will require a lock as well. This can be expressed using the BSLMF_NESTED_TRAIT_DECLARATION_IF macro, by providing abcd::RequiresLockTrait<ELEMENT>value as the condition for associating the trait with Container.

  template <class ELEMENT>
  struct Container {
      // ...

    public:
      // TRAITS
      BSLMF_NESTED_TRAIT_DECLARATION_IF(Container, abcd::RequiresLockTrait,
                                    abcd::RequiresLockTrait<ELEMENT>::value);

      // ...
  };

Next, we show that traits based on bslmf::DetectNestedTrait can be associated with a type using "C++11-style" trait association. To do this, we declare a type, RequiresLockTypeB, that also requires the lock, but does not used the BSLMF_NESTED_TRAIT_DECLARATION macro:

  class RequiresLockTypeB {
      // ...

    public:
      // CREATORS
      RequiresLockTypeB();
          // ...

  };

  } // close package namespace

Then, we associate RequiresLockTypeB with abcd::RequiresLockTrait by directly specializing abcd::RequiresLockTrait<xyza::RequiresLockTypeB>. This is the standard way of associating a type with a trait since C++11:

  namespace abcd {

  template <>
  struct RequiresLockTrait<xyza::RequiresLockTypeB> : bsl::true_type {
  };

  } // close namespace abcd

Now, we can write a function that inspects abcd::RequiresLockTrait<t_TYPE>value to test whether or not various types are associated with abcd::RequiresLockTrait:

  void example1()
  {
      assert(false ==
             abcd::RequiresLockTrait<xyza::DoesNotRequireLockType>::value);

      assert(true  ==
             abcd::RequiresLockTrait<xyza::RequiresLockTypeA>::value);

      assert(true  ==
             abcd::RequiresLockTrait<xyza::RequiresLockTypeB>::value);

      assert(false ==
             abcd::RequiresLockTrait<
                     xyza::Container<xyza::DoesNotRequireLockType> >::value);

      assert(true  ==
             abcd::RequiresLockTrait<
                          xyza::Container<xyza::RequiresLockTypeA> >::value);

      assert(true  ==
             abcd::RequiresLockTrait<
                          xyza::Container<xyza::RequiresLockTypeB> >::value);

      // ...
  }

Finally, we demonstrate that the trait can be tested at compilation time, by writing a function that tests the trait within the context of a compile-time BSLMF_ASSERT:

  void example2()
  {
      BSLMF_ASSERT(false ==
             abcd::RequiresLockTrait<xyza::DoesNotRequireLockType>::value);

      BSLMF_ASSERT(true  ==
             abcd::RequiresLockTrait<xyza::RequiresLockTypeA>::value);

      BSLMF_ASSERT(true  ==
             abcd::RequiresLockTrait<xyza::RequiresLockTypeB>::value);

      BSLMF_ASSERT(false ==
             abcd::RequiresLockTrait<
                     xyza::Container<xyza::DoesNotRequireLockType> >::value);

      BSLMF_ASSERT(true  ==
             abcd::RequiresLockTrait<
                          xyza::Container<xyza::RequiresLockTypeA> >::value);

      BSLMF_ASSERT(true  ==
             abcd::RequiresLockTrait<
                          xyza::Container<xyza::RequiresLockTypeB> >::value);

  }

Component bslmf_detectnestedtrait [Package bslmf]

Namespaces

Detailed Description

Component bslmf_detectnestedtrait
[Package bslmf]