|
Flow 1.0.0
Flow project: Public API.
|
A light-weight class, each object storing a component payload encoding an enum value from enum type of user's choice, and a light-weight ID of that enum type itself.
More...
#include <log.hpp>
Public Types | |
| using | enum_raw_t = unsigned int |
The type Payload must be enum class Payload : enum_raw_t: an enum type encoded via this integer type. | |
Public Member Functions | |
| Component () | |
Constructs a Component that stores no payload; meaning an unspecified-component Component that returns empty() == true. More... | |
| template<typename Payload > | |
| Component (Payload payload) | |
Constructs a Component with the given payload of arbitrary type, so long as that type is an enum class : Component::enum_raw_t. More... | |
| Component (const Component &src) | |
Copies the source Component into *this. More... | |
| Component (Component &&src_moved) | |
Constructs *this equal to src_moved. More... | |
| Component & | operator= (const Component &src) |
Overwrites *this with a copy of src. More... | |
| template<typename Payload > | |
| Component & | operator= (Payload new_payload) |
Equivalent to operator=(Component<Payload>(new_payload)) modulo possibly minor perf differences. More... | |
| Component & | operator= (Component &&src_moved) |
Makes *this equal to src_moved. More... | |
| bool | empty () const |
Returns true if *this is as if default-constructed (a null Component); false if as if constructed via the 1-arg constructor (a non-null Component). More... | |
| template<typename Payload > | |
| Payload | payload () const |
Returns reference to immutable payload stored in *this; undefined behavior if empty() == true. More... | |
| const std::type_info & | payload_type () const |
Returns typeid(Payload), where Payload was the template param used when calling the originating one-arg constructor or equivalent; undefined behavior if empty() == true. More... | |
| std::type_index | payload_type_index () const |
Convenience accessor that returns std::type_index(payload_type()), which can be used most excellently to store things in associative containers (like std::map) keyed by disparate Component payload enum types. More... | |
| enum_raw_t | payload_enum_raw_value () const |
Returns the numeric value of the enum payload stored by this Component, originating in the one-arg constructor; undefined behavior if empty() == true. More... | |
A light-weight class, each object storing a component payload encoding an enum value from enum type of user's choice, and a light-weight ID of that enum type itself.
A Component is supplied by the user, at every logging call site, along with the message. Log_context (or FLOW_LOG_SET_CONTEXT() in relatively rare scenarios) makes this easier, so typically user need not literally type out a component at every logging call site, meaning there is a "context" that already stores it and need not be re-specified.
A Component can be either empty, as when default-constructed, indicated by empty() returning true; or non-empty, in which case it actually stores something interesting. In the latter case, construct it with the templated one-arg constructor. The template arg Payload must, always, be user's own enum class. In order to have this Payload interpreted correctly, one can (and usually should) use the log::Config facility which is used by out-of-the-box Logger implementations including Simple_ostream_logger (useful for console output) and Async_file_logger (for heavy-duty file logging, including rotation support). However, this is technically optional: one can implement their own Logger which might not use the Config facility and thus deal with the meaning of Component in some completely different way. I'd start with an existing Logger implementation however; and if writing one's own Logger, then still have it use log::Config, unless that system is somehow insufficient or inappropriate.
Tip: Arguably the best way to see how to use all this together, just see flow::Flow_log_component and how Flow's own code (which, itself, logs!) uses the log system. This is discussed in more detail in the class Config doc header. Lastly, some clarifying discussion may be found (as of this writing) in the Component::type_info() doc header.
A Component is immutable as of this writing, except one can trivially overwrite a Component via an assignment operator. The latter write operation is not thread-safe w.r.t. a given *this, though in practice this is unlikely to ever matter.
| flow::log::Component::Component | ( | ) |
Constructs a Component that stores no payload; meaning an unspecified-component Component that returns empty() == true.
Every Logger and all other systems must accept a message with such a null Component. However, one can configure a given Logger to ensure such messages not be logged (filtered out via should_log()). Point is, any log call site that supplied a null Component must still work, meaning not cause undefined behavior.
| flow::log::Component::Component | ( | Payload | payload | ) |
Constructs a Component with the given payload of arbitrary type, so long as that type is an enum class : Component::enum_raw_t.
(enum_raw_t is an unsigned integer type.) The resulting Component will return empty() == false.
| Payload | The type of the component value stored inside *this. This is required to be a type satisfying the requirements in the doc header for enum_raw_t. |
| payload | The payload value copied into *this and whenever a Component itself is copied (or moved). |
|
default |
Copies the source Component into *this.
This involves a single payload copy (and not even that if src.empty()).
| src | Object to copy. |
|
default |
Constructs *this equal to src_moved.
In this implementation it is equivalent to the copy constructor.
| src_moved | Object to move. |
| bool flow::log::Component::empty | ( | ) | const |
Makes *this equal to src_moved.
In this implementation it is equivalent to copy assignment.
| src_moved | Object to move. |
*this. Overwrites *this with a copy of src.
| src | Object to copy. |
*this. | Component & flow::log::Component::operator= | ( | Payload | new_payload | ) |
Equivalent to operator=(Component<Payload>(new_payload)) modulo possibly minor perf differences.
| new_payload | See non-default constructor. |
*this. | Payload flow::log::Component::payload |
Returns reference to immutable payload stored in *this; undefined behavior if empty() == true.
| Payload | See one-arg ctor doc header. |
| Component::enum_raw_t flow::log::Component::payload_enum_raw_value | ( | ) | const |
| const std::type_info & flow::log::Component::payload_type | ( | ) | const |
Returns typeid(Payload), where Payload was the template param used when calling the originating one-arg constructor or equivalent; undefined behavior if empty() == true.
flow::log user that relies fully on an out-of-the-box Logger, or on a custom Logger that nevertheless fully uses the log::Config facility, is unlikely to need this information. (It is used internally by log::Config.) However, a custom Logger that decided to use an alternative Component mechanism (as opposed to how log::Config and reliant Loggers do) can use this payload_type() method to distinguish between potential source enums that were passed to the Logger at each given log call site.
For example, consider that Flow itself, for its own logging, uses the flow::Flow_log_component enum at all log call sites. Imagine you, the user, have decided to generate your own flow::log messages and always use your own enum class cool_project::Cool_log_component at your own logging call sites. Then, a typical component specification will look like this respectively:
Now, this->get_log_component().payload_type() will equal that of Flow_log_component and Cool_log_component, respectively, within those 2 classes. In particular, a custom Logger implementation can use payload_type() – and in particular the derived payload_type_index() – to interpret the Components of values from the 2 entirely disparate enums in different ways. More in particular, the out-of-the-box Loggers use Config to do all of that without your having to worry about it (but your own Logger would potentially have to worry about it particularly if not using log::Config... though we suggest that you should, barring excellent design counter-reasons).
| std::type_index flow::log::Component::payload_type_index | ( | ) | const |
Convenience accessor that returns std::type_index(payload_type()), which can be used most excellently to store things in associative containers (like std::map) keyed by disparate Component payload enum types.
(E.g., such a map might have one entry for Flow's own flow::Flow_log_component; one for the example cool_project::Cool_log_component enumeration mentioned in the payload_type() doc header; and so on for any logging modules in your process. Again, log::Config will do that for you, if you choose to use it in your custom Logger.)
1.9.4