{
"title": "warning",
"category": "diagnostics",
"keywords": [
"warning",
"diagnostics",
"state",
"query",
"backtrace"
],
"summary": "Display formatted warnings, control warning state, and query per-identifier settings.",
"references": [],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [],
"broadcasting": "none",
"notes": "Runs entirely on the host. GPU tensors appearing in formatted arguments are gathered before formatting."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 0,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::diagnostics::warning::tests",
"integration": null
},
"description": "`warning` emits diagnostic messages without aborting execution. It also provides a central interface for enabling, disabling, promoting, or querying warnings by identifier.\n\nRunMat mirrors MATLAB semantics with per-identifier modes (`'on'`, `'off'`, `'once'`, `'error'`), backtrace control, structured state restoration, and formatted message support. When an identifier is promoted to `'error'`, future uses of that warning raise an error instead of printing.",
"behaviors": [
"`warning(message)` prints the message using the default identifier `RunMat:warning`.",
"`warning(id, fmt, args...)` associates the warning with the identifier `id`, formats the message using MATLAB's `sprintf` rules, and honours per-identifier state.",
"`warning(MException_obj)` reissues an existing exception as a warning.",
"`warning(struct)` restores warning state previously captured with `warning('query', ...)`.",
"`warning(state, id)` changes the mode for `id` (`'on'`, `'off'`, `'once'`, `'error'`, and the aliases `'all'` or `'last'`). The call returns a struct describing the prior state so you can restore it later.",
"`warning(state, mode)` controls diagnostic verbosity modes such as `'backtrace'` and `'verbose'`, returning a struct snapshot of the previous setting.",
"`warning('default', id)` resets `id` (or `'all'`, `'backtrace'`, `'verbose'`, `'last'`) to the factory default, returning the state that was active before the reset. `warning('reset')` restores every warning, mode, and once-tracking flag in one call.",
"`warning('query', id)` returns a struct describing the current mode for `id`. Passing `'all'` returns a cell vector of structs covering every configured identifier plus the global default and diagnostic modes.",
"`warning('status')` prints the global warning table as a formatted summary.",
"All state-changing forms return struct snapshots; pass them back to `warning` later to reinstate the captured state."
],
"examples": [
{
"description": "Displaying a simple warning",
"input": "warning(\"Computation took longer than expected.\")"
},
{
"description": "Emitting a warning with a custom identifier",
"input": "warning(\"runmat:io:deprecatedOption\", ...\n \"Option '%s' is deprecated and will be removed in %s.\", ...\n \"VerboseMode\", \"1.2\")"
},
{
"description": "Turning a specific warning off and back on",
"input": "warning(\"off\", \"runmat:io:deprecatedOption\");\n% ... code that triggers the warning ...\nwarning(\"on\", \"runmat:io:deprecatedOption\")"
},
{
"description": "Promoting a warning to an error",
"input": "warning(\"error\", \"runmat:solver:illConditioned\");\n% The next call raises an error instead of printing a warning.\nwarning(\"runmat:solver:illConditioned\", ...\n \"Condition number exceeds threshold %.2e.\", 1e12)"
},
{
"description": "Querying and restoring warning state",
"input": "state = warning(\"query\", \"all\"); % capture the current table\nwarning(\"off\", \"all\"); % silence all warnings temporarily\nwarning(\"Some temporary warning.\");\nwarning(state); % restore original configuration"
},
{
"description": "Enabling backtraces for debugging",
"input": "warning(\"on\", \"backtrace\"); % warning(\"backtrace\",\"on\") is equivalent\nwarning(\"runmat:demo:slowPath\", \"Inspect the call stack above for context.\");\nwarning(\"off\", \"backtrace\")"
},
{
"description": "Displaying verbose suppression guidance",
"input": "warning(\"on\", \"verbose\");\nwarning(\"runmat:demo:slowPath\", \"Inspect the call stack above for context.\");\nwarning(\"default\", \"verbose\"); % restore the default verbosity"
}
],
"faqs": [
{
"question": "Does RunMat keep track of the last warning?",
"answer": "Yes. The last identifier and message are stored internally and will be exposed through the MATLAB-compatible `lastwarn` builtin."
},
{
"question": "What does `'once'` do?",
"answer": "The first occurrence of the warning is shown, and subsequent uses of the same identifier are suppressed until you change the state."
},
{
"question": "How do I restore defaults after experimentation?",
"answer": "Call `warning('reset')` to revert the global default, per-identifier table, diagnostic modes, and once-tracking."
},
{
"question": "Do state-changing calls return anything useful?",
"answer": "Yes. Forms such as `warning('off','id')`, `warning('on','backtrace')`, and `warning('default')` return struct snapshots describing the state before the change. Store the struct and pass it back to `warning` later to restore the captured configuration."
},
{
"question": "What does the `'verbose'` mode do?",
"answer": "When enabled (`warning('on','verbose')`), RunMat prints an additional hint describing how to suppress the warning. Disable it with `warning('default','verbose')`."
},
{
"question": "What happens when a warning is promoted to `'error'`?",
"answer": "The warning text is reused to raise an error with the same identifier, just like MATLAB."
},
{
"question": "Does `warning` run on the GPU?",
"answer": "No. Control-flow builtins execute on the host. GPU inputs referenced in formatted messages are gathered automatically before the message is emitted."
},
{
"question": "Can I provide multiple state structs to `warning(state)`?",
"answer": "Yes. Pass either a struct or a cell array of structs (as returned by `warning('query','all')`); RunMat applies them sequentially."
},
{
"question": "Does `warning('on','backtrace')` match MATLAB output exactly?",
"answer": "RunMat prints a Rust backtrace for now. Future releases will map this to MATLAB-style stack frames, but the enable/disable semantics match MATLAB."
},
{
"question": "Is whitespace in identifiers allowed?",
"answer": "Identifiers follow MATLAB rules: they must contain at least one colon and no whitespace. RunMat normalises bare names by prefixing `RunMat:`."
},
{
"question": "What if I call `warning` with unsupported arguments?",
"answer": "RunMat issues a MATLAB-compatible usage error so you can correct the call."
},
{
"question": "Are repeated calls thread-safe?",
"answer": "Internally the warning table is guarded by a mutex, so concurrent invocations are serialised and remain deterministic."
}
],
"links": [
{
"label": "error",
"url": "./error"
},
{
"label": "sprintf",
"url": "./sprintf"
},
{
"label": "fprintf",
"url": "./fprintf"
},
{
"label": "assert",
"url": "./assert"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/diagnostics/warning.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/diagnostics/warning.rs"
},
"gpu_residency": "`warning` is a control-flow builtin that runs on the host. When formatted arguments include GPU resident arrays (for example via `%g` specifiers), RunMat gathers the values to host memory before formatting the message so the diagnostic text matches MATLAB expectations.",
"gpu_behavior": [
"`warning` is a control-flow builtin that runs on the host. When formatted arguments include GPU resident arrays (for example via `%g` specifiers), RunMat gathers the values to host memory before formatting the message so the diagnostic text matches MATLAB expectations."
]
}