From 57c3f938221c427b78da7087f8a832ba4a271a7c Mon Sep 17 00:00:00 2001
From: Julius Ikkala <julius.ikkala@gmail.com>
Date: Fri, 23 May 2025 22:27:37 +0300
Subject: Implement throw & catch statements (#6916)

* Implement throw statement

It already existed in the IR, so only parsing, checking and lowering was
missing.

* Initial catch implementation

Likely very broken.

* Error out when catch() isn't last in scope

* Prevent accessing variables from scope preceding catch

As those may actually not be available at that point.

* Add IError and use it in Result type lowering

* Add diagnostic tests

* Allow caught throws in non-throw functions

* Fix catch propagating between functions & SPIR-V merge issue

* Add test for non-trivial error types

* Fix MSVC build

* Fix invalid value type from Result lowering

* Also lower error handling in templates

* Lower result types only after specialization

* Attempt to disambiguate error enums by witness table

* Revert matching by witness, types should be distinct too

* Don't assert valueField when getting Result's error value

It may not exist if the function returns void, but getting the error
value is still legitimate.

* Update tests for new error numbers & get rid of expected.txt

* Change catch lowering to resemble breaking a loop

... To make SPIR-V happy.

* Fix dead catch blocks and invalid cached dominator tree

* More SPIR-V adjustment

* Lower catch as two nested loops

* Add defer interaction test and revert broken defer changes

* Fix enum type when throwing literals

* Cleanup and bikeshedding

* Document error handling mechanism

* Fix table of contents

* Use boolean tag in Result<T, E>

* Use anyValue storage for Result<T,E>

* Remove IError

* Fix formatting

* Eradicate success values from docs and tests

* Use parseModernParamDecl for catch parameter

* Implement do-catch syntax

* Implement catch-all

* Fix formatting

* Fix marshalling native calls that throw

---------

Co-authored-by: Yong He <yonghe@outlook.com>
---
 docs/user-guide/03-convenience-features.md | 65 ++++++++++++++++++++++++++++++
 docs/user-guide/toc.html                   |  1 +
 2 files changed, 66 insertions(+)

(limited to 'docs/user-guide')

diff --git a/docs/user-guide/03-convenience-features.md b/docs/user-guide/03-convenience-features.md
index 5646292aa..d522daf81 100644
--- a/docs/user-guide/03-convenience-features.md
+++ b/docs/user-guide/03-convenience-features.md
@@ -793,6 +793,71 @@ by using the `[ForceInline]` decoration:
 int f(int x) { return x + 1; }
 ```
 
+Error handling
+-----------------
+
+Slang supports an error handling mechanism that is superficially similar to
+exceptions in many other languages, but has some unique characteristics.
+
+In contrast to C++ exceptions, this mechanism makes the control flow of errors
+more explicit, and the performance charasteristics are similar to adding an
+if-statement after every potentially throwing function call to check and handle
+the error.
+
+In order to be able to throw an error, a function must declare the type of that
+error with `throws`:
+```
+enum MyError
+{
+    Failure,
+    CatastrophicFailure
+}
+
+int f() throws MyError
+{
+    if (computerIsBroken())
+        throw MyError.CatastrophicFailure;
+    return 42;
+}
+```
+Currently, functions may only throw a single type of error.
+
+To call a function that may throw, you must prepend it with `try`:
+
+```
+let result = try f();
+```
+
+If you don't catch the `try`, related errors are re-thrown and the calling
+function must declare that it `throws` that error type:
+
+```
+void g() throws MyError
+{
+    // This would not compile if `g()` wasn't declared to throw MyError as well.
+    let result = try f();
+    printf("Success: %d\n", result);
+}
+```
+
+To catch an error, you can use a `do-catch` statement:
+
+```
+void g()
+{
+    do
+    {
+        let result = try f();
+        printf("Success: %d\n", result);
+    }
+    catch(err: MyError)
+    {
+        printf("Not good!\n");
+    }
+}
+```
+
+You can chain multiple catch statements for different types of errors.
 
 Special Scoping Syntax
 -------------------
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index 47e0c05ad..c83f36282 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -49,6 +49,7 @@
 <li data-link="convenience-features#extensions"><span>Extensions</span></li>
 <li data-link="convenience-features#multi-level-break"><span>Multi-level break</span></li>
 <li data-link="convenience-features#force-inlining"><span>Force inlining</span></li>
+<li data-link="convenience-features#error-handling"><span>Error handling</span></li>
 <li data-link="convenience-features#special-scoping-syntax"><span>Special Scoping Syntax</span></li>
 <li data-link="convenience-features#user-defined-attributes-experimental"><span>User Defined Attributes (Experimental)</span></li>
 </ul>
-- 
cgit v1.2.3