/rust/registry/src/index.crates.io-1949cf8c6b5b557f/flexi_logger-0.27.4/src/parameters.rs

Source
/// Criterion when to rotate the log file.
///
/// Used in [`Logger::rotate`](crate::Logger::rotate).
#[derive(Copy, Clone, Debug)]
pub enum Criterion {
    /// Rotate the log file when it exceeds the specified size in bytes.
    Size(u64),
    /// Rotate the log file when it has become older than the specified age.
    ///
    /// ## Minor limitation
    ///
    /// ### TL,DR
    /// the combination of `Logger::append()`
    /// with `Criterion::Age` works OK, but not perfectly correct on Windows or unix
    /// when the program is restarted.
    ///
    /// ### Details
    /// Applying the age criterion works fine while your program is running.
    /// Ideally, we should also apply it to the rCURRENT file when the program is restarted
    /// and you chose the `Logger::append()` option.
    ///
    /// Unfortunately, this does not work on Windows, and it does not work on unix,
    /// for different reasons.
    ///
    /// To minimize the impact on age-based file-rotation,
    /// `flexi_logger` uses on Windows, and on all other platforms where the creation date
    /// of a file is not available (like on Unix), the last modification date
    /// (or, if this is also not available, the current time stamp)
    /// as the created_at-info of an rCURRENT file that already exists, and the
    /// current timestamp when file rotation happens during further execution.
    /// Consequently, a left-over rCURRENT file from a previous program run will look newer
    /// than it is, and will be used longer than it should be.
    ///
    /// #### Issue on Windows
    ///
    /// For compatibility with DOS (sic!), Windows magically transfers the created_at-info
    /// of a file that is deleted (or renamed) to its successor,
    /// when the recreation happens within some seconds [\[1\]](#ref-1).
    ///
    /// If the file property were used by `flexi_logger`,
    /// the rCURRENT file would always appear to be as old as the
    /// first one that ever was created - rotation by time would completely fail.
    ///
    /// <a name="ref-1">\[1\]</a> [https://superuser.com/questions/966490/windows-7-what-is-date-created-file-property-referring-to](https://superuser.com/questions/966490/windows-7-what-is-date-created-file-property-referring-to).
    ///
    Age(Age),
    /// Rotate the file when it has either become older than the specified age, or when it has
    /// exceeded the specified size in bytes.
    ///
    /// See documentation for Age and Size.
    AgeOrSize(Age, u64),
}

/// The age after which a log file rotation will be triggered,
/// when [`Criterion::Age`] is chosen.
#[derive(Copy, Clone, Debug)]
pub enum Age {
    /// Rotate the log file when the local clock has started a new day since the
    /// current file had been created.
    Day,
    /// Rotate the log file when the local clock has started a new hour since the
    /// current file had been created.
    Hour,
    /// Rotate the log file when the local clock has started a new minute since the
    /// current file had been created.
    Minute,
    /// Rotate the log file when the local clock has started a new second since the
    /// current file had been created.
    Second,
}

/// The naming convention for rotated log files.
///
/// Common rule for all variants is that the names of the current output file
/// and the rotated log files only differ in the infix.
///
/// See [`Logger::log_to_file`](crate::Logger::log_to_file)
/// for a description of how the filename is built, including the infix.
///
/// See the variants for how the infix is used by them.
///
/// Used in [`Logger::rotate`](crate::Logger::rotate).
#[derive(Copy, Clone, Debug)]
pub enum Naming {
    /// Logs are written to a file with infix `_rCURRENT`.
    ///
    /// File rotation renames this file to a name with a timestamp-infix
    /// like `"_r2023-01-27_14-41-08"`, logging continues with a fresh file with infix `_rCURRENT`.
    ///
    /// If multiple rotations happen within the same second, extended infixes are used like
    /// `"_r2023-01-27_14-41-08.restart-0001"`.
    Timestamps,

    /// Logs are written to a file with a timestamp-infix,
    /// like `"_r2023-01-27_14-41-08"`.
    ///
    /// File rotation switches over to the next file.
    ///
    /// If multiple rotations happen within the same second, extended infixes are used like
    /// `"_r2023-01-27_14-41-08.restart-0001"`.
    TimestampsDirect,

    /// Logs are written to a file with infix `_rCURRENT`.
    ///
    /// File rotation renames this file to a name with a number-infix
    /// like `"_r00000"`, `"_r00001"`, etc.,
    /// logging continues with a fresh file with infix `_rCURRENT`.
    Numbers,

    /// Logs are written to a file with a number-infix,
    /// like `"_r00000"`, `"_r00001"`, etc.
    ///
    /// File rotation switches over to the next file.
    NumbersDirect,
}
impl Naming {
    pub(crate) fn writes_direct(self) -> bool {
        matches!(self, Naming::NumbersDirect | Naming::TimestampsDirect)
    }
}

/// Defines the strategy for handling older log files.
///
/// Is used in [`Logger::rotate`](crate::Logger::rotate).
///
/// Note that if you use a strategy other than `Cleanup::Never`, then the cleanup work is
/// by default done in an extra thread, to minimize the impact on the program.
///
/// See [`LoggerHandle::shutdown`](crate::LoggerHandle::shutdown)
/// to avoid interrupting a currently active cleanup when your program terminates.
///
/// See
/// [`Logger::cleanup_in_background_thread`](crate::Logger::cleanup_in_background_thread)
/// if you want to control whether this extra thread is created and used.
#[derive(Copy, Clone, Debug)]
pub enum Cleanup {
    /// Older log files are not touched - they remain for ever.
    Never,

    /// The specified number of rotated log files are kept.
    /// Older files are deleted, if necessary.
    KeepLogFiles(usize),

    /// The specified number of rotated log files are compressed and kept.
    /// Older files are deleted, if necessary.
    #[cfg_attr(docsrs, doc(cfg(feature = "compress")))]
    #[cfg(feature = "compress")]
    KeepCompressedFiles(usize),

    /// Allows keeping some files as text files and some as compressed files.
    ///
    /// ## Example
    ///
    /// `KeepLogAndCompressedFiles(5,30)` ensures that the youngest five log files are
    /// kept as text files, the next 30 are kept as compressed files with additional suffix `.gz`,
    /// and older files are removed.
    #[cfg_attr(docsrs, doc(cfg(feature = "compress")))]
    #[cfg(feature = "compress")]
    KeepLogAndCompressedFiles(usize, usize),
}

impl Cleanup {
    // Returns true if some cleanup is to be done.
    #[must_use]
    pub(crate) fn do_cleanup(&self) -> bool {
        !matches!(self, Self::Never)
    }
}

Coverage Report

Created: 2025-10-28 06:54

Line	Count	Source
1		/// Criterion when to rotate the log file.
2		///
3		/// Used in [`Logger::rotate`](crate::Logger::rotate).
4		#[derive(Copy, Clone, Debug)]
5		pub enum Criterion {
6		/// Rotate the log file when it exceeds the specified size in bytes.
7		Size(u64),
8		/// Rotate the log file when it has become older than the specified age.
9		///
10		/// ## Minor limitation
11		///
12		/// ### TL,DR
13		/// the combination of `Logger::append()`
14		/// with `Criterion::Age` works OK, but not perfectly correct on Windows or unix
15		/// when the program is restarted.
16		///
17		/// ### Details
18		/// Applying the age criterion works fine while your program is running.
19		/// Ideally, we should also apply it to the rCURRENT file when the program is restarted
20		/// and you chose the `Logger::append()` option.
21		///
22		/// Unfortunately, this does not work on Windows, and it does not work on unix,
23		/// for different reasons.
24		///
25		/// To minimize the impact on age-based file-rotation,
26		/// `flexi_logger` uses on Windows, and on all other platforms where the creation date
27		/// of a file is not available (like on Unix), the last modification date
28		/// (or, if this is also not available, the current time stamp)
29		/// as the created_at-info of an rCURRENT file that already exists, and the
30		/// current timestamp when file rotation happens during further execution.
31		/// Consequently, a left-over rCURRENT file from a previous program run will look newer
32		/// than it is, and will be used longer than it should be.
33		///
34		/// #### Issue on Windows
35		///
36		/// For compatibility with DOS (sic!), Windows magically transfers the created_at-info
37		/// of a file that is deleted (or renamed) to its successor,
38		/// when the recreation happens within some seconds [\[1\]](#ref-1).
39		///
40		/// If the file property were used by `flexi_logger`,
41		/// the rCURRENT file would always appear to be as old as the
42		/// first one that ever was created - rotation by time would completely fail.
43		///
44		/// <a name="ref-1">\[1\]</a> [https://superuser.com/questions/966490/windows-7-what-is-date-created-file-property-referring-to](https://superuser.com/questions/966490/windows-7-what-is-date-created-file-property-referring-to).
45		///
46		Age(Age),
47		/// Rotate the file when it has either become older than the specified age, or when it has
48		/// exceeded the specified size in bytes.
49		///
50		/// See documentation for Age and Size.
51		AgeOrSize(Age, u64),
52		}
53
54		/// The age after which a log file rotation will be triggered,
55		/// when [`Criterion::Age`] is chosen.
56		#[derive(Copy, Clone, Debug)]
57		pub enum Age {
58		/// Rotate the log file when the local clock has started a new day since the
59		/// current file had been created.
60		Day,
61		/// Rotate the log file when the local clock has started a new hour since the
62		/// current file had been created.
63		Hour,
64		/// Rotate the log file when the local clock has started a new minute since the
65		/// current file had been created.
66		Minute,
67		/// Rotate the log file when the local clock has started a new second since the
68		/// current file had been created.
69		Second,
70		}
71
72		/// The naming convention for rotated log files.
73		///
74		/// Common rule for all variants is that the names of the current output file
75		/// and the rotated log files only differ in the infix.
76		///
77		/// See [`Logger::log_to_file`](crate::Logger::log_to_file)
78		/// for a description of how the filename is built, including the infix.
79		///
80		/// See the variants for how the infix is used by them.
81		///
82		/// Used in [`Logger::rotate`](crate::Logger::rotate).
83		#[derive(Copy, Clone, Debug)]
84		pub enum Naming {
85		/// Logs are written to a file with infix `_rCURRENT`.
86		///
87		/// File rotation renames this file to a name with a timestamp-infix
88		/// like `"_r2023-01-27_14-41-08"`, logging continues with a fresh file with infix `_rCURRENT`.
89		///
90		/// If multiple rotations happen within the same second, extended infixes are used like
91		/// `"_r2023-01-27_14-41-08.restart-0001"`.
92		Timestamps,
93
94		/// Logs are written to a file with a timestamp-infix,
95		/// like `"_r2023-01-27_14-41-08"`.
96		///
97		/// File rotation switches over to the next file.
98		///
99		/// If multiple rotations happen within the same second, extended infixes are used like
100		/// `"_r2023-01-27_14-41-08.restart-0001"`.
101		TimestampsDirect,
102
103		/// Logs are written to a file with infix `_rCURRENT`.
104		///
105		/// File rotation renames this file to a name with a number-infix
106		/// like `"_r00000"`, `"_r00001"`, etc.,
107		/// logging continues with a fresh file with infix `_rCURRENT`.
108		Numbers,
109
110		/// Logs are written to a file with a number-infix,
111		/// like `"_r00000"`, `"_r00001"`, etc.
112		///
113		/// File rotation switches over to the next file.
114		NumbersDirect,
115		}
116		impl Naming {
117	0	pub(crate) fn writes_direct(self) -> bool {
118	0	matches!(self, Naming::NumbersDirect \| Naming::TimestampsDirect)
119	0	}
120		}
121
122		/// Defines the strategy for handling older log files.
123		///
124		/// Is used in [`Logger::rotate`](crate::Logger::rotate).
125		///
126		/// Note that if you use a strategy other than `Cleanup::Never`, then the cleanup work is
127		/// by default done in an extra thread, to minimize the impact on the program.
128		///
129		/// See [`LoggerHandle::shutdown`](crate::LoggerHandle::shutdown)
130		/// to avoid interrupting a currently active cleanup when your program terminates.
131		///
132		/// See
133		/// [`Logger::cleanup_in_background_thread`](crate::Logger::cleanup_in_background_thread)
134		/// if you want to control whether this extra thread is created and used.
135		#[derive(Copy, Clone, Debug)]
136		pub enum Cleanup {
137		/// Older log files are not touched - they remain for ever.
138		Never,
139
140		/// The specified number of rotated log files are kept.
141		/// Older files are deleted, if necessary.
142		KeepLogFiles(usize),
143
144		/// The specified number of rotated log files are compressed and kept.
145		/// Older files are deleted, if necessary.
146		#[cfg_attr(docsrs, doc(cfg(feature = "compress")))]
147		#[cfg(feature = "compress")]
148		KeepCompressedFiles(usize),
149
150		/// Allows keeping some files as text files and some as compressed files.
151		///
152		/// ## Example
153		///
154		/// `KeepLogAndCompressedFiles(5,30)` ensures that the youngest five log files are
155		/// kept as text files, the next 30 are kept as compressed files with additional suffix `.gz`,
156		/// and older files are removed.
157		#[cfg_attr(docsrs, doc(cfg(feature = "compress")))]
158		#[cfg(feature = "compress")]
159		KeepLogAndCompressedFiles(usize, usize),
160		}
161
162		impl Cleanup {
163		// Returns true if some cleanup is to be done.
164		#[must_use]
165	0	pub(crate) fn do_cleanup(&self) -> bool {
166	0	!matches!(self, Self::Never)
167	0	}
168		}