Class attribute_value

boost::log::attribute_value — An attribute value class.

Synopsis

// In header: <boost/log/attributes/attribute_value.hpp>


class attribute_value {
public:
  // member classes/structs/unions

  // A base class for an attribute value implementation.

  struct impl : public attribute::impl {

    // public member functions
    virtual bool dispatch(type_dispatcher &) = 0;
    virtual intrusive_ptr< impl > detach_from_thread();
    virtual attribute_value get_value();
    virtual typeindex::type_index get_type() const;
  };

  // public member functions
  attribute_value() = default;
  attribute_value(attribute_value const &) noexcept;
  attribute_value(attribute_value &&) noexcept;
  explicit attribute_value(intrusive_ptr< impl >) noexcept;
  attribute_value & operator=(attribute_value const &) noexcept;
  attribute_value & operator=(attribute_value &&) noexcept;
  explicit operator bool() const noexcept;
  bool operator!() const noexcept;
  typeindex::type_index get_type() const;
  void detach_from_thread();
  bool dispatch(type_dispatcher &) const;
  template<typename T, typename TagT = void> 
    result_of::extract< T, TagT >::type extract() const;
  template<typename T, typename TagT = void> 
    result_of::extract_or_throw< T, TagT >::type extract_or_throw() const;
  template<typename T, typename TagT = void> 
    result_of::extract_or_default< T, T, TagT >::type 
    extract_or_default(T const &) const;
  template<typename T, typename TagT = void, typename DefaultT> 
    result_of::extract_or_default< T, DefaultT, TagT >::type 
    extract_or_default(DefaultT const &) const;
  template<typename T, typename VisitorT> 
    visitation_result visit(VisitorT) const;
  void swap(attribute_value &) noexcept;
};

Description

An attribute value is an object that contains a piece of data that represents an attribute state at the point of the value acquisition. All major operations with log records, such as filtering and formatting, involve attribute values contained in a single view. Most likely an attribute value is implemented as a simple holder of some typed value. This holder implements the attribute_value::implementation interface and acts as a pimpl for the attribute_value object. The attribute_value class provides type dispatching support in order to allow to extract the value from the holder.

Normally, attributes and their values shall be designed in order to exclude as much interference as reasonable. Such approach allows to have more than one attribute value simultaneously, which improves scalability and allows to implement generating attributes.

However, there are cases when this approach does not help to achieve the required level of independency of attribute values and attribute itself from each other at a reasonable performance tradeoff. For example, an attribute or its values may use thread-specific data, which is global and shared between all the instances of the attribute/value. Passing such an attribute value to another thread would be a disaster. To solve this the library defines an additional method for attribute values, namely detach_from_thread. The attribute_value class forwards the call to its pimpl, which is supposed to ensure that it no longer refers to any thread-specific data after the call. The pimpl can create a new holder as a result of this method and return it to the attribute_value wrapper, which will keep the returned reference for any further calls. This method is called for all attribute values that are passed to another thread.

`attribute_value` public member functions

```
attribute_value() = default;
```
Default constructor. Creates an empty (absent) attribute value.

attribute_value(attribute_value const & that) noexcept;

Copy constructor

attribute_value(attribute_value && that) noexcept;

Move constructor

```
explicit attribute_value(intrusive_ptr< impl > p) noexcept;
```
Initializing constructor. Creates an attribute value that refers to the specified holder.

Parameters:

p

A pointer to the attribute value holder.

attribute_value & operator=(attribute_value const & that) noexcept;

Copy assignment

attribute_value & operator=(attribute_value && that) noexcept;

Move assignment

```
explicit operator bool() const noexcept;
```
The operator checks if the attribute value is empty
```
bool operator!() const noexcept;
```
The operator checks if the attribute value is empty
```
typeindex::type_index get_type() const;
```
The method returns the type information of the stored value of the attribute. The returned type info wrapper may be empty if the attribute value is empty or the information cannot be provided. If the returned value is not empty, the type can be used for value extraction.
```
void detach_from_thread();
```
The method is called when the attribute value is passed to another thread (e.g. in case of asynchronous logging). The value should ensure it properly owns all thread-specific data.

Postconditions:

The attribute value no longer refers to any thread-specific resources.

bool dispatch(type_dispatcher & dispatcher) const;

The method dispatches the value to the given object. This method is a low level interface for attribute value visitation and extraction. For typical usage these interfaces may be more convenient.

Parameters:

dispatcher

The object that attempts to dispatch the stored value.

Returns:

true if the value is not empty and the dispatcher was capable to consume the real attribute value type and false otherwise.

template<typename T, typename TagT = void> 
  result_of::extract< T, TagT >::type extract() const;

The method attempts to extract the stored value, assuming the value has the specified type. One can specify either a single type or an MPL type sequence, in which case the stored value is checked against every type in the sequence.

	Note
	Include `value_extraction.hpp` prior to using this method.

Returns:

The extracted value, if the attribute value is not empty and the value is the same as specified. Otherwise returns an empty value. See description of the result_of::extract metafunction for information on the nature of the result value.

template<typename T, typename TagT = void> 
  result_of::extract_or_throw< T, TagT >::type extract_or_throw() const;

	Note
	Include `value_extraction.hpp` prior to using this method.

Returns:

The extracted value, if the attribute value is not empty and the value is the same as specified. Otherwise an exception is thrown. See description of the result_of::extract_or_throw metafunction for information on the nature of the result value.

template<typename T, typename TagT = void> 
  result_of::extract_or_default< T, T, TagT >::type 
  extract_or_default(T const & def_value) const;

	Note
	Include `value_extraction.hpp` prior to using this method.

Parameters:

def_value

Default value.

Returns:

The extracted value, if the attribute value is not empty and the value is the same as specified. Otherwise returns the default value. See description of the result_of::extract_or_default metafunction for information on the nature of the result value.

template<typename T, typename TagT = void, typename DefaultT> 
  result_of::extract_or_default< T, DefaultT, TagT >::type 
  extract_or_default(DefaultT const & def_value) const;

	Note
	Include `value_extraction.hpp` prior to using this method.

Parameters:

def_value

Default value.

Returns:

template<typename T, typename VisitorT> 
  visitation_result visit(VisitorT visitor) const;

The method attempts to extract the stored value, assuming the value has the specified type, and pass it to the visitor function object. One can specify either a single type or an MPL type sequence, in which case the stored value is checked against every type in the sequence.

	Note
	Include `value_visitation.hpp` prior to using this method.

Parameters:

visitor

A function object that will be invoked on the extracted attribute value. The visitor should be capable to be called with a single argument of any type of the specified types in T.

Returns:

The result of visitation.

void swap(attribute_value & that) noexcept;

The method swaps two attribute values

Boost C++ Libraries