Update tutorial

Author: alvinng4

content/tutorial.mdx

@@ -2,60 +2,254 @@
 title: "Tutorial"
 description: "Tutorial for C Traceback"
 author: "Ching-Yin Ng"
-date: "2025-12-30"
+date: "2025-12-31"
 ---
 
 # Tutorial
 
-<Callout>This is an example of `layout:'full'`</Callout>
-
-```typescript
-// app/_meta.global.tsx
-export default {
-     contact: {
-        type: 'page',
-        theme: {
-            layout: 'full',
-            toc: false,
-            timestamp: false,
-        }
+<Callout>This tutorial is not finished yet</Callout>
+
+## Project Setup
+
+For demonstration, let us start with a simple vector calculation project.
+Below is the sample code written with C99. It does four things:
+
+1. Allocate memory for vector.
+2. Initialize values for vector.
+3. Divide every vector element by denominator.
+4. Clean up.
+
+Let us look at them one by one.
+```c
+/**
+ * \file: project.c
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "c_traceback.h"
+
+int main(void)
+{
+    const size_t n = 1000;     // Vector size
+    const double denominator = 123.0;
+
+    /* Allocate memory */
+
+    /* Initialize values */
+
+    /* Division */
+
+    /* Clean up */
+
+    return 0;
+
+error_clean_up:
+    /* Error clean up */
+
+    return 1;
+}
+```
+
+## Allocate memory
+For demonstrative purpose, let us try allocating memory by using a function.
+Below is what I would write in C99:
+```c
+int alloc_memory(double **arr, const size_t n)
+{
+    *arr = malloc(n * sizeof(double));
+    if (!(*arr))
+    {
+        return 1;   // Failed to allocate memory
+    }
+    return 0;
+}
+```
+While the function is fine for a simple project, it is better to have an error traceback
+and error message so that users know what happened without having to go through
+your source code.
+
+### `RAISE_ERROR` <Badge text="Macro" />
+We can first make use of the `RAISE_ERROR` macro.
+Instead of returning a value, we raise an error instead.
+```c /void/ {6-7}
+void alloc_memory(double **arr, const size_t n)
+{
+    *arr = malloc(n * sizeof(double));
+    if (!(*arr))
+    {
+        // Failed to allocate memory
+        RAISE_ERROR(CTB_MEMORY_ERROR, "Failed to allocate memory for vector!");
     }
 }
 ```
+However, it doesn't do much by itself. It only silently records an error.
+We will have to modify some code in the `main` function.
+
+### `TRACE` <Badge text="Macro" />
+On the outer scope, we can wrap our function call with `TRACE`, which
+returns an boolean error value. On top of that, `TRACE` will manage
+the call stack automatically for you.
+```c /TRACE/
+/* Allocate memory */
+double *arr;
+if (!TRACE(alloc_memory(&arr, n)))
+{
+    goto error_clean_up;
+}
+```
+
+### `TRY_GOTO` <Badge text="Macro" />
+`TRY_GOTO` does the same thing as `TRACE`, but it jumps to a label when
+the expression fails.
+```c /TRY_GOTO
+/* Allocate memory */
+double *arr;
+TRY_GOTO(alloc_memory(&arr, n), error_clean_up);
+```
+
+## Clean up
+### `ctb_dump_traceback` <Badge text="Function" />
+Now, add `ctb_dump_traceback` at the error handling. It will log the traceback to `stderr`
+and reset the internal error status.
+```c
+int main(void)
+{
+    /* Clean up */
+    free(arr);
+    return 0;
+
+error_clean_up:
+    /* Error clean up */
+    free(arr);
+    ctb_dump_traceback();
+    return 1;
+}
+```
+Below is the final code. Lets set `n` to 1000000000000000 to see what happens.
+```c {10, 14, 19, 26, 31-32, 36-44}
+/**
+ * \file: project.c
+ */
+ 
+#include <stdio.h>
+#include <stdlib.h>
+ 
+#include "c_traceback.h"
+
+void alloc_memory(double **arr, const size_t n);
+ 
+int main(void)
+{
+    const size_t n = 1000000000000000;     // Vector size
+    const double denominator = 123.0;
+ 
+    /* Allocate memory */
+    double *arr;
+    TRY_GOTO(alloc_memory(&arr, n), error_clean_up);
+ 
+    /* Initialize values */
+ 
+    /* Division */
+ 
+    /* Clean up */
+    free(arr);
+    return 0;
+ 
+error_clean_up:
+    /* Error clean up */
+    free(arr);
+    ctb_dump_traceback();
+    return 1;
+}
+ 
+void alloc_memory(double **arr, const size_t n)
+{
+    *arr = malloc(n * sizeof(double));
+    if (!(*arr))
+    {
+        // Failed to allocate memory
+        RAISE_ERROR(CTB_MEMORY_ERROR, "Failed to allocate memory for vector!");
+    }
+}
 
-We'd love to hear from you! Whether you have a question, feedback, or just want to say hello, feel free to reach out.
+```
+#### Output
+`n` is too big to be allocated on any single computer.
+You should see the traceback below.
+<Callout type="info">If you don't see the traceback, turn off optimization flags by using `-O0` as compilers could optimize the malloc away.</Callout>
+```ansi
+--------------------------------------------------
+Traceback (most recent call last):
+  (#00) File "/Users/alvinng/Desktop/project/project.c", line 19 in main:
+    alloc_memory(&arr, n)
+  (#01) File "/Users/alvinng/Desktop/project/project.c", line 42 in alloc_memory:
+    <Error raised here>
+MemoryError: Failed to allocate memory for vector!
+--------------------------------------------------
+```
 
-## Get in Touch
 
-You can contact us through any of the following methods:
 
-### Email
-**General Inquiries:** [email protected]
-**Support:** [email protected]
-**Sales:** [email protected]
 
-### Phone
-**Main Office:** +1 (555) 123-4567
-**Support Hotline:** +1 (555) 987-6543
+```c
+/**
+ * \file: project.c
+ */
 
-### Address
-123 Main Street
-Suite 100
-San Francisco, CA 94102
-United States
+#include <stdio.h>
+#include <stdlib.h>
 
-## Business Hours
+int alloc_memory(double **arr);
+void division(double *arr, double denominator, const int n);
 
-- **Monday - Friday:** 9:00 AM - 6:00 PM PST
-- **Saturday:** 10:00 AM - 4:00 PM PST
-- **Sunday:** Closed
+int main(void)
+{
+    const int n = 1000;     // Vector size
+    const double denominator = 123.0;
 
-## Contact Form
+    /* Allocate memory */
+    double *arr;
+    if (!alloc_memory(&arr, n))
+    {
+        goto error;
+    }
 
-Fill out the form below and we'll get back to you within 24 hours:
+    /* Initialize values */
+    for (int i = 0; i < n; i++)
+    {
+        arr[i] = i;
+    }
 
-*(Contact form would be integrated here)*
+    /* Do calculation */
+    division(arr, denominator, n);
+    
+    /* Clean up */
+    free(arr);
+    return 0;
+
+error:
+    /* Error clean up */
+    free(arr);
+    return 1;
+}
 
----
+int alloc_memory(double **arr, const int n)
+{
+    *arr = malloc(N * sizeof(double));
+    if (!(*arr))
+    {
+        return 1;   // Failed to allocate memory
+    }
+    return 0;
+}
 
-*We typically respond to all inquiries within 1-2 business days.*
+void division(double *arr, double denominator, const int n)
+{
+    for (int i = 0; i < n; i++)
+    {
+        arr[i] /= denominator;
+    }
+}
+```

mdx-components.tsx

@@ -1,5 +1,5 @@
 import {useMDXComponents as getThemeComponents} from 'nextra-theme-docs';
-import {Callout, FileTree} from "nextra/components";
+import {Callout, FileTree, Tabs} from "nextra/components";
 
 import { Badge } from "components/ui/badge";
 
@@ -13,5 +13,6 @@ export function useMDXComponents() {
         Badge: Badge,
         Callout: Callout,
         FileTree: FileTree,
+        Tabs: Tabs,
     }
 }