...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::log::attribute_value — An attribute value class.
// 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; }; // construct/copy/destruct 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; // public member functions 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; };
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
construct/copy/destructattribute_value(attribute_value const & that) noexcept;
Default constructor. Creates an empty (absent) attribute value.
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: |
|
attribute_value & operator=(attribute_value const & that) noexcept;
Copy assignment
attribute_value & operator=(attribute_value && that) noexcept;
Move assignment
attribute_value
public member functionsexplicit 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: |
|
||
Returns: |
|
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 |
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 |
template<typename T, typename TagT = void> result_of::extract_or_throw< T, TagT >::type extract_or_throw() 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 |
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 |
template<typename T, typename TagT = void> result_of::extract_or_default< T, T, TagT >::type extract_or_default(T const & def_value) 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. If extraction fails, the default value is returned.
Note | |
---|---|
Include |
Parameters: |
|
||
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 |
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;
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. If extraction fails, the default value is returned.
Note | |
---|---|
Include |
Parameters: |
|
||
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 |
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 |
Parameters: |
|
||
Returns: |
The result of visitation. |
void swap(attribute_value & that) noexcept;
The method swaps two attribute values