Class LogHandle
Defined in File log.h
Inheritance Relationships
Derived Type
public CE::Logging::Log< name >(Template Class Log)
Class Documentation
-
class LogHandle
An owned logger facade.
Engine holds its queue, destinations, registry and native implementation. Formatting occurs only after the destination probe.
Subclassed by CE::Logging::Log< name >
Public Functions
-
~LogHandle()
Release facade ownership; final backend ownership closes/drains its accepted output.
Stop callers before destruction. Retained queue/backend state and process logging lifetime govern actual native cleanup.
See also
-
LogHandle(const LogHandle&) = delete
Copy/move facade ownership is disabled; use a named Logger or explicitly owned Log instead.
See also
-
LogHandle &operator=(const LogHandle&) = delete
Copy/move facade ownership is disabled; use a named Logger or explicitly owned Log instead.
See also
-
LogHandle(LogHandle&&) = delete
Copy/move facade ownership is disabled; use a named Logger or explicitly owned Log instead.
See also
-
LogHandle &operator=(LogHandle&&) = delete
Copy/move facade ownership is disabled; use a named Logger or explicitly owned Log instead.
See also
-
const Config &initial_configuration() const noexcept
Declaration:
[[nodiscard]]Borrow immutable startup settings with the normalized absolute directory.
See also
- Returns:
Reference valid during facade/backend lifetime. Live level changes affect current generations and survive close/reopen, but do not mutate this snapshot.
Declaration:
[[nodiscard]]Sample independently maintained shared logging-pool counters.
See also
- Returns:
Owned counts across all categories, including discarded flush requests and excluding worker-taken items. Available while closed; reopen does not reset totals.
-
BackendStats backend_stats() const noexcept
Declaration:
[[nodiscard]]Sample cumulative failures and the last published generation’s degradation.
See also
- Returns:
Owned independently sampled counters; completed close/reopen clears degradation, not cumulative history.
-
void report_diagnostics() const
Emit bounded coalesced stdio observations outside lifecycle locks.
Available while closed and emitted by completed close. This observes failures without redirecting the original exception or proving output durability.
See also
-
std::filesystem::path get_file_path() const
Declaration:
[[nodiscard]]Copy the configured absolute log-file path; does not reopen or refresh a closed destination.
See also
-
std::uint16_t get_log_id() const
Declaration:
[[nodiscard]]Read the backend’s process-local compact log identifier; not a persistent globally unique key.
See also
-
void flush() const
Enqueue a flush using this log’s overflow policy.
May wait for shared queue capacity or discard/count the request. It does not acknowledge backend completion or physical durability; backend/lifecycle reentry rejects.
See also
-
void close(std::chrono::milliseconds timeout = std::chrono::milliseconds::zero())
Stop accepting writes and wait for accepted file ownership to close.
See also
- Parameters:
timeout – Zero waits indefinitely; a finite timeout bounds this wait. Stop producers first. Timeout throws failed_operation and leaves Closing intact for a later close; completed close does not promise physical durability. Backend callback reentry or invalid lifecycle transitions reject.
-
void reopen()
Reopen a completed Closed log using retained settings and live level configuration.
An already Open log is unchanged; Opening/Closing rejects. Native/open-callback errors propagate without publishing a completed generation. Process logging shutdown is terminal and forbids reopen.
See also
-
void make_default() const
Select this open logger in Engine’s private native registry.
Does not replace an application’s independently configured native default logger. Closed/transitional state or backend reentry rejects.
See also
-
void set_level_logger(Level level) const
Change the live category gate on an open log.
See also
- Parameters:
level – Valid runtime threshold; off suppresses output without closing destinations. The threshold survives close/reopen but cannot enable compiled-out severities. Closed/transitional state and backend reentry reject.
-
void set_level_filesink(Level level) const
Change the live file destination gate on an open log.
See also
- Parameters:
level – Valid runtime threshold; off suppresses output without closing destinations. The threshold survives close/reopen but cannot enable compiled-out severities. Closed/transitional state and backend reentry reject.
-
void set_level_stdsink(Level level) const
Change the live console destination gate on an open log.
See also
- Parameters:
level – Valid runtime threshold; off suppresses output without closing destinations. The threshold survives close/reopen but cannot enable compiled-out severities. Closed/transitional state and backend reentry reject.
-
bool should_log(Level level) const noexcept
Declaration:
[[nodiscard]]Probe compilation, logger and healthy destination gates before expensive argument preparation.
See also
- Parameters:
level – Runtime severity to inspect.
- Returns:
Best-effort admission at this instant; false while closing/closed or recursively inside backend activity. A level change/close can race a later write. Ordinary call arguments are evaluated before entering a severity method; use lazy submission to avoid that preparation.
-
void set_pattern(const char *format) const
Set formatting for both destinations on the open log.
See also
- Parameters:
format – Borrowed valid native pattern string consumed by the operation, not a std::format message. Closed/transitional state or backend reentry rejects; destination pattern parsing errors propagate.
-
void set_pattern_filesink(const char *format) const
Set formatting for the file destination on the open log.
See also
- Parameters:
format – Borrowed valid native pattern string consumed by the operation, not a std::format message. Closed/transitional state or backend reentry rejects; destination pattern parsing errors propagate.
-
void set_pattern_stdsink(const char *format) const
Set formatting for the console destination on the open log.
See also
- Parameters:
format – Borrowed valid native pattern string consumed by the operation, not a std::format message. Closed/transitional state or backend reentry rejects; destination pattern parsing errors propagate.
-
void strace(void *address = nullptr) const
Submit a stack trace through the configured trace gate.
See also
- Parameters:
address – Optional stack-trace origin; nullptr requests the current trace. Compilation/destination gates can suppress it; it is ordinary logging, not an emergency/noexcept callback facility.
-
template<typename ...Args>
inline void trace(std::format_string<Args...> format, Args&&... arguments) const Format and submit an ordinary trace record only when compiled and admitted.
See also
- Template Parameters:
Args – Types accepted by the checked std::format string.
- Parameters:
format – Compile-time checked message format.
arguments – Forwarded formatting inputs; expressions are evaluated before this call. Formatting/submission can allocate or throw and Block overflow can wait. Closing/closed/degraded destinations suppress output. Do not call from locks, native/noexcept callbacks or the logging backend; lazy diagnostics handle preparation failures separately.
-
template<typename ...Args>
inline void debug(std::format_string<Args...> format, Args&&... arguments) const Format and submit an ordinary debug record only when compiled and admitted.
See also
- Template Parameters:
Args – Types accepted by the checked std::format string.
- Parameters:
format – Compile-time checked message format.
arguments – Forwarded formatting inputs; expressions are evaluated before this call. Formatting/submission can allocate or throw and Block overflow can wait. Closing/closed/degraded destinations suppress output. Do not call from locks, native/noexcept callbacks or the logging backend; lazy diagnostics handle preparation failures separately.
-
template<typename ...Args>
inline void info(std::format_string<Args...> format, Args&&... arguments) const Format and submit an ordinary info record only when compiled and admitted.
See also
- Template Parameters:
Args – Types accepted by the checked std::format string.
- Parameters:
format – Compile-time checked message format.
arguments – Forwarded formatting inputs; expressions are evaluated before this call. Formatting/submission can allocate or throw and Block overflow can wait. Closing/closed/degraded destinations suppress output. Do not call from locks, native/noexcept callbacks or the logging backend; lazy diagnostics handle preparation failures separately.
-
template<typename ...Args>
inline void warn(std::format_string<Args...> format, Args&&... arguments) const Format and submit an ordinary warning record only when compiled and admitted.
See also
- Template Parameters:
Args – Types accepted by the checked std::format string.
- Parameters:
format – Compile-time checked message format.
arguments – Forwarded formatting inputs; expressions are evaluated before this call. Formatting/submission can allocate or throw and Block overflow can wait. Closing/closed/degraded destinations suppress output. Do not call from locks, native/noexcept callbacks or the logging backend; lazy diagnostics handle preparation failures separately.
-
template<typename ...Args>
inline void error(std::format_string<Args...> format, Args&&... arguments) const Format and submit an ordinary error record only when compiled and admitted.
See also
- Template Parameters:
Args – Types accepted by the checked std::format string.
- Parameters:
format – Compile-time checked message format.
arguments – Forwarded formatting inputs; expressions are evaluated before this call. Formatting/submission can allocate or throw and Block overflow can wait. Closing/closed/degraded destinations suppress output. Do not call from locks, native/noexcept callbacks or the logging backend; lazy diagnostics handle preparation failures separately.
-
template<typename ...Args>
inline void critical(std::format_string<Args...> format, Args&&... arguments) const Format and submit an ordinary critical record only when compiled and admitted.
See also
- Template Parameters:
Args – Types accepted by the checked std::format string.
- Parameters:
format – Compile-time checked message format.
arguments – Forwarded formatting inputs; expressions are evaluated before this call. Formatting/submission can allocate or throw and Block overflow can wait. Closing/closed/degraded destinations suppress output. Critical submission also includes its trace behavior. Do not call from locks, native/noexcept callbacks or the logging backend; lazy diagnostics handle preparation failures separately.
Protected Functions
-
LogHandle(const char *name, FileEventHandlers handlers, Config config)
Construct owned backend state for a valid category and initial configuration.
See also
- Parameters:
name – Nonempty filename component with no slash/backslash.
handlers – Owned callbacks with protected capture lifetime through closure.
config – Valid rotation/level/overflow settings; relative directory resolves once before publication. Opening/validation/callback failures propagate. Requires a live process logging lifetime; no backend callback may reenter construction.
Retain already constructed Engine logging state for an internal derived facade.
See also
- Parameters:
state – Valid non-null backend state; this protected path does not construct another native logger.
-
~LogHandle()