JosiahWI commented on code in PR #13262:
URL: https://github.com/apache/trafficserver/pull/13262#discussion_r3403589692
##########
include/tscore/DiagsTypes.h:
##########
@@ -107,29 +128,88 @@ class DiagsConfigState
class Diags : public DebugInterface
{
public:
+ /// @brief Initializes the Diags logging subsystem.
+ ///
+ /// @param prefix_string Non-empty string prepended to every log line.
+ /// @param base_debug_tags Initial debug tag regex pattern, or nullptr to
disable
+ /// debug output. Vertical-bar-separated (e.g., "http|cache").
+ /// @param base_action_tags Initial action tag regex pattern, or nullptr to
disable.
+ /// @param _diags_log BaseLogFile for the primary diagnostics log, or nullptr
+ /// if no diags log is desired.
+ /// @param diags_log_perm File permissions for the diags log (-1 to inherit).
+ /// @param output_log_perm File permissions for stdout/stderr redirects (-1
to inherit).
+ /// @pre prefix_string must not be empty.
+ /// @post stdout_log and stderr_log are initialized and open. diags_log is
open
+ /// if _diags_log was non-null and the file was accessible; otherwise
nullptr.
+ /// Rolling is disabled by default. cleanup_func is nullptr.
+ /// @note Thread safety: call from the main thread during single-threaded
startup.
+ /// No concurrent logging may occur until construction is complete.
Diags(std::string_view prefix_string, const char *base_debug_tags, const
char *base_action_tags, BaseLogFile *_diags_log,
int diags_log_perm = -1, int output_log_perm = -1);
+
+ /// @brief Closes all log file handles and releases tag resources.
+ ///
+ /// @pre No concurrent logging or configuration changes may be in progress.
+ /// @post All log file handles are closed and freed. Tag regex objects are
released.
+ /// @note Thread safety: call only during shutdown when no other threads are
+ /// actively calling logging methods.
virtual ~Diags();
+ /// Primary diagnostics log file (e.g., diags.log).
+ /// May be nullptr if no diagnostics log was configured or if the file could
+ /// not be opened at initialization. Replaced atomically under the internal
+ /// lock during log rotation and reseat operations. Do not cache this pointer
+ /// across calls that may trigger rotation.
BaseLogFile *diags_log;
+
+ /// stdout redirect log file. Never nullptr after construction.
+ /// Replaced atomically under the internal lock during set_std_output()
+ /// and output log rolling. Do not cache this pointer.
BaseLogFile *stdout_log;
Review Comment:
Correct, but downvoting because Copilot suggested removing the `stdout_log`
symbol which would result in compilation failure.
##########
include/tscore/DiagsTypes.h:
##########
@@ -107,29 +128,88 @@ class DiagsConfigState
class Diags : public DebugInterface
{
public:
+ /// @brief Initializes the Diags logging subsystem.
+ ///
+ /// @param prefix_string Non-empty string prepended to every log line.
+ /// @param base_debug_tags Initial debug tag regex pattern, or nullptr to
disable
+ /// debug output. Vertical-bar-separated (e.g., "http|cache").
+ /// @param base_action_tags Initial action tag regex pattern, or nullptr to
disable.
+ /// @param _diags_log BaseLogFile for the primary diagnostics log, or nullptr
+ /// if no diags log is desired.
+ /// @param diags_log_perm File permissions for the diags log (-1 to inherit).
+ /// @param output_log_perm File permissions for stdout/stderr redirects (-1
to inherit).
+ /// @pre prefix_string must not be empty.
+ /// @post stdout_log and stderr_log are initialized and open. diags_log is
open
+ /// if _diags_log was non-null and the file was accessible; otherwise
nullptr.
+ /// Rolling is disabled by default. cleanup_func is nullptr.
+ /// @note Thread safety: call from the main thread during single-threaded
startup.
+ /// No concurrent logging may occur until construction is complete.
Diags(std::string_view prefix_string, const char *base_debug_tags, const
char *base_action_tags, BaseLogFile *_diags_log,
int diags_log_perm = -1, int output_log_perm = -1);
+
+ /// @brief Closes all log file handles and releases tag resources.
+ ///
+ /// @pre No concurrent logging or configuration changes may be in progress.
+ /// @post All log file handles are closed and freed. Tag regex objects are
released.
+ /// @note Thread safety: call only during shutdown when no other threads are
+ /// actively calling logging methods.
virtual ~Diags();
+ /// Primary diagnostics log file (e.g., diags.log).
+ /// May be nullptr if no diagnostics log was configured or if the file could
+ /// not be opened at initialization. Replaced atomically under the internal
+ /// lock during log rotation and reseat operations. Do not cache this pointer
+ /// across calls that may trigger rotation.
BaseLogFile *diags_log;
+
+ /// stdout redirect log file. Never nullptr after construction.
+ /// Replaced atomically under the internal lock during set_std_output()
+ /// and output log rolling. Do not cache this pointer.
BaseLogFile *stdout_log;
+
+ /// stderr redirect log file. Never nullptr after construction.
+ /// Replaced atomically under the internal lock during set_std_output()
+ /// and output log rolling. Do not cache this pointer.
BaseLogFile *stderr_log;
Review Comment:
Same as above.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
