JosiahWI commented on code in PR #13262:
URL: https://github.com/apache/trafficserver/pull/13262#discussion_r3403468290
##########
include/tscore/DiagsTypes.h:
##########
@@ -220,26 +383,150 @@ class Diags : public DebugInterface
va_end(ap);
}
+ /// @brief Variadic implementation of error().
+ ///
+ /// @param level Diagnostic severity level.
+ /// @param loc Optional source location. May be nullptr.
+ /// @param fmt printf-style format string.
+ /// @param ap Argument list for fmt.
+ /// @post Message is written. Process exits if level is terminal.
+ /// @note Thread-safe for the output step. Virtual to allow test overrides.
virtual void error_va(DiagsLevel level, const SourceLocation *loc, const
char *fmt, va_list ap) const;
+ /// @brief Writes a human-readable summary of the current Diags
configuration.
+ ///
+ /// @param fp Output FILE stream. Defaults to stdout.
+ /// @pre fp must be a valid open stream.
+ /// @post A formatted table of enabled states, tag patterns, and output
+ /// routing is written to fp.
+ /// @note Not intended for production code paths. Configuration is read
+ /// without the internal lock; output is informational only.
void dump(FILE *fp = stdout) const;
+ /// @brief Replaces the active tag filter with the compiled form of taglist.
+ ///
+ /// @param taglist Vertical-bar-separated regex pattern (e.g., "http|dns"),
+ /// or nullptr to clear the active pattern.
+ /// @param mode DiagsTagType_Debug or DiagsTagType_Action.
+ /// @pre taglist, if non-null, must be a valid regex pattern.
+ /// @post Subsequent on(tag, mode) calls match against the new pattern.
+ /// If this is the global Diags instance, DbgCtl's tag cache is
updated.
+ /// @note Thread-safe. The regex is compiled outside the internal lock; only
+ /// the pointer swap is performed under the lock.
void activate_taglist(const char *taglist, DiagsTagType mode =
DiagsTagType_Debug);
+ /// @brief Clears the active tag filter, disabling all tag-based output for
mode.
+ ///
+ /// @param mode DiagsTagType_Debug or DiagsTagType_Action.
+ /// @post on(tag, mode) returns false for all tags until activate_taglist()
+ /// is called again. If this is the global Diags instance, DbgCtl's
+ /// cache is updated.
+ /// @note Thread-safe. Acquires the internal lock for the pointer reset.
void deactivate_all(DiagsTagType mode = DiagsTagType_Debug);
+ /// @brief Opens blf and assigns it as the diagnostics log.
+ ///
+ /// @param blf A BaseLogFile pointing to the desired log path, or nullptr
+ /// to leave the diagnostics log unchanged.
+ /// @return true if blf was nullptr or was opened successfully.
+ /// false if blf could not be opened (blf is deleted and an error
+ /// is written to stderr).
+ /// @pre If blf is non-null, it must not already be open.
+ /// @post On success, diags_log points to the opened blf.
+ /// On failure, diags_log is unchanged and blf is freed.
+ /// @note Thread safety: intended for single-threaded initialization.
+ /// For runtime reseat, use reseat_diagslog() instead.
bool setup_diagslog(BaseLogFile *blf);
+
+ /// @brief Configures automatic rolling for the diagnostics log.
+ ///
+ /// @param re Rolling mode (NO_ROLLING, ROLL_ON_TIME, ROLL_ON_SIZE,
+ /// ROLL_ON_TIME_OR_SIZE).
+ /// @param ri Roll interval in seconds for time-based rolling (-1 to
disable).
+ /// @param rs Roll size threshold in megabytes for size-based rolling (-1 to
disable).
+ /// @post should_roll_diagslog() uses the new configuration on the next call.
+ /// @note Call during initialization or single-threaded configuration only.
void config_roll_diagslog(RollingEnabledValues re, int ri, int rs);
+
+ /// @brief Configures automatic rolling for stdout and stderr output logs.
+ ///
+ /// @param re Rolling mode.
+ /// @param ri Roll interval in seconds (-1 to disable).
+ /// @param rs Roll size threshold in megabytes (-1 to disable).
+ /// @post should_roll_outputlog() uses the new configuration on the next
call.
+ /// @note Call during initialization or single-threaded configuration only.
void config_roll_outputlog(RollingEnabledValues re, int ri, int rs);
+
+ /// @brief Reopens the diagnostics log at its current configured path.
+ ///
+ /// Closes the current file descriptor and opens a new one at the same path,
+ /// allowing the log to continue writing to a freshly created file after an
+ /// external tool has renamed or moved the previous one.
+ ///
+ /// @return true if diags_log was initialized (regardless of whether the
+ /// reopen succeeded). false if diags_log is nullptr or
uninitialized.
+ /// @pre diags_log may or may not point to an existing file on disk.
+ /// @post On success: diags_log points to a new file opened at the original
+ /// path. The old file descriptor is closed.
+ /// On failure to reopen: diags_log is unchanged; the old descriptor
+ /// remains in use.
+ /// @note Thread-safe. The current log is flushed and the new file is opened
+ /// outside the internal lock; only the pointer swap is performed
+ /// under the lock. Safe to call while concurrent logging is active.
Review Comment:
There is a data race between this function and `should_roll_diagslog` which
contradicts the documentation here.
--
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]
