os/log/
macros.rs

1//! 日志宏
2//!
3//! 该模块提供了 **Linux 内核风格的日志宏** (`pr_*`)，用于以不同优先级级别进行轻松日志记录。
4//!
5//! # 用法
6//!
7//! ```rust
8//! use crate::pr_info;
9//! use crate::pr_err;
10//!
11//! pr_info!("系统已初始化");
12//! pr_err!("分配 {} 字节失败", size);
13//! pr_warn!("内存使用率为 {}%", percent);
14//! pr_debug!("变量 x = {}", x);
15//! ```
16//!
17//! # 宏列表
18//!
19//! - `pr_emerg!` - 紧急级别（系统不可用）
20//! - `pr_alert!` - 警报级别（需要立即采取行动）
21//! - `pr_crit!` - 关键级别（关键状况）
22//! - `pr_err!` - 错误级别（错误状况）
23//! - `pr_warn!` - 警告级别（警告状况）
24//! - `pr_notice!` - 通知级别（正常但重要）
25//! - `pr_info!` - 信息级别（信息性消息）
26//! - `pr_debug!` - 调试级别（调试消息）
27//!
28//! # 性能
29//!
30//! 所有宏都在**宏展开时检查全局日志级别**。如果某个日志级别被禁用，则永远不会评估格式字符串，这使得**禁用的日志开销基本上为零**。
31
32/// 带有级别过滤的内部实现宏
33///
34/// 在调用日志记录实现之前，**检查日志级别是否启用**。
35/// 这种早期检查避免了对禁用级别进行不必要的格式化字符串评估。
36#[macro_export]
37macro_rules! __log_impl_filtered {
38    ($level:expr, $args:expr) => {
39        if $crate::log::is_level_enabled($level) {
40            $crate::log::log_impl($level, $args);
41        }
42    };
43}
44
45/// 以 **EMERGENCY (紧急)** 级别记录消息
46///
47/// 紧急日志表示系统不可用。这些日志始终会打印到控制台（如果控制台输出可用）并存储在缓冲区中。
48///
49/// # 示例
50///
51/// ```rust
52/// pr_emerg!("内核恐慌: {}", reason);
53/// pr_emerg!("系统中止");
54/// ```
55#[macro_export]
56macro_rules! pr_emerg {
57($($arg:tt)*) => {
58$crate::__log_impl_filtered!(
59$crate::log::LogLevel::Emergency,
60format_args!($($arg)*)
61)
62}
63}
64
65/// 以 **ALERT (警报)** 级别记录消息
66///
67/// 警报日志表示必须立即采取行动。
68///
69/// # 示例
70///
71/// ```rust
72/// pr_alert!("检测到关键硬件故障");
73/// ```
74#[macro_export]
75macro_rules! pr_alert {
76    ($($arg:tt)*) => {
77        $crate::__log_impl_filtered!(
78            $crate::log::LogLevel::Alert,
79            format_args!($($arg)*)
80        )
81    }
82}
83
84/// 以 **CRITICAL (关键)** 级别记录消息
85///
86/// 关键日志表示需要关注的关键状况。
87///
88/// # 示例
89///
90/// ```rust
91/// pr_crit!("温度阈值已超出");
92/// ```
93#[macro_export]
94macro_rules! pr_crit {
95    ($($arg:tt)*) => {
96        $crate::__log_impl_filtered!(
97            $crate::log::LogLevel::Critical,
98            format_args!($($arg)*)
99        )
100    }
101}
102
103/// 以 **ERROR (错误)** 级别记录消息
104///
105/// 错误日志表示在操作过程中发生的错误状况。
106///
107/// # 示例
108///
109/// ```rust
110/// pr_err!("分配 {} 字节失败", size);
111/// pr_err!("设备初始化失败: {}", error);
112/// ```
113#[macro_export]
114macro_rules! pr_err {
115    ($($arg:tt)*) => {
116        $crate::__log_impl_filtered!(
117            $crate::log::LogLevel::Error,
118            format_args!($($arg)*)
119        )
120    }
121}
122
123/// 以 **WARNING (警告)** 级别记录消息
124///
125/// 警告日志表示应审查但不妨碍正常操作的状况。
126///
127/// # 示例
128///
129/// ```rust
130/// pr_warn!("内存使用率为 {}%", percent);
131/// pr_warn!("使用了已弃用的功能");
132/// ```
133#[macro_export]
134macro_rules! pr_warn {
135    ($($arg:tt)*) => {
136        $crate::__log_impl_filtered!(
137            $crate::log::LogLevel::Warning,
138            format_args!($($arg)*)
139        )
140    }
141}
142
143/// 以 **NOTICE (通知)** 级别记录消息
144///
145/// 通知日志表示正常但重要的状况。
146///
147/// # 示例
148///
149/// ```rust
150/// pr_notice!("设备 {} 已连接", device_name);
151/// ```
152#[macro_export]
153macro_rules! pr_notice {
154    ($($arg:tt)*) => {
155        $crate::__log_impl_filtered!(
156            $crate::log::LogLevel::Notice,
157            format_args!($($arg)*)
158        )
159    }
160}
161
162/// 以 **INFO (信息)** 级别记录消息
163///
164/// 信息日志提供有关正常系统操作的信息性消息。
165///
166/// # 示例
167///
168/// ```rust
169/// pr_info!("内核已初始化");
170/// pr_info!("正在启动子系统 {}", name);
171/// ```
172#[macro_export]
173macro_rules! pr_info {
174    ($($arg:tt)*) => {
175        $crate::__log_impl_filtered!(
176            $crate::log::LogLevel::Info,
177            format_args!($($arg)*)
178        )
179    }
180}
181
182/// 以 **DEBUG (调试)** 级别记录消息
183///
184/// 调试日志提供详细的诊断信息，用于故障排除。
185/// 这些日志通常在生产版本中被禁用。
186///
187/// # 示例
188///
189/// ```rust
190/// pr_debug!("调用函数时 x = {}", x);
191/// pr_debug!("状态转换: {} -> {}", old_state, new_state);
192/// ```
193#[macro_export]
194macro_rules! pr_debug {
195    ($($arg:tt)*) => {
196        $crate::__log_impl_filtered!(
197            $crate::log::LogLevel::Debug,
198            format_args!($($arg)*)
199        )
200    }
201}
os/log/macros.rs

os/log/
macros.rs
