2025: Add "Translate DRuntime Hooks to Templates" project

- Give an overall description of DRuntime hooks
- Provide concrete requirements for templating hooks
- Provide external resources for contributors

Signed-off-by: Teodor Dutu <[email protected]>

gsoc-2025/template-hooks.md

@@ -0,0 +1,122 @@
+---
+parent: DLang GSoC 2025 Project Ideas
+nav_order: 1
+---
+
+# Translate DRuntime Hooks to Templates
+
+**Mentor:** [Teodor Duțu]([email protected])
+
+| Spec | Details |
+|-|-|
+| **Difficulty Level** | hard |
+| **Project Duration** | 350 hours |
+| **Number of Contributors** | 2 |
+| **Prerequisites** | Familiarity with compilers, build systems; low-level programming |
+
+## Description
+
+High-level language constructs are often compiled into lower-level function calls that implement the same functionality.
+This process is called _lowering_
+It compiler design by offloading complex code into simpler function calls.
+These functions are implemented in D's runtime library (called DRuntime) and are commonly called [_runtime hooks_](https://wiki.dlang.org/Runtime_Hooks).
+
+Below is an example of such a runtime hook:
+
+```d
+struct S { ... }
+
+S[3] a, b;
+
+// Original code
+b = a;  // b is a copy of a 
+
+// Resulting DRuntime hook
+_d_arrayassign_l(b, a)  // copies a into b
+```
+
+`_d_arrayassign_l` handles array (re)allocation and assignment operators according to the types of `a` and `b` (`S[3]`) to simplify the compiler's work.
+
+As shown in the example above, runtime hooks require type information, such as which assignment operator to call and the arrays' sizes.
+D supports templates, but runtime hooks pre-date the introduction of templates to D.
+Therefore, they retrieve the necessary type information at runtime by receiving an extra argument, whose type is [`TypeInfo`](https://dlang.org/library/object/type_info.html).
+This object contains the size, constructors, destructors and overloaded operators of a given type.
+However, because this information is processed at run time, this approach is slower to the alternative of having the compiler send it to the runtime hook via template arguments.
+Due to D's high flexibility regarding metaprogramming, translating each hook to a template function would allow its code to specialise TODO
+
+So far the following hooks have been converted to templates:
+
+```text
+_d_arrayctor
+_d_arraysetctor
+_d_arrayassign
+_d_arrayassign_l
+_d_arrayassign_r
+_d_delstruct
+_d_newThrowable
+_d_arrayappendT
+_d_arrayappendcTX
+_d_arraycatT
+_d_arraycatnTX
+_d_newitemiT
+_d_newitemT
+_d_newitemU
+_d_newclass
+_d_newarrayiT
+_d_newarrayT
+_d_newarrayU
+_d_newarraymTX
+_d_newarrayOpT
+```
+
+In general, these are the steps required to convert a runtime hook to a template:
+
+1. Implement a new template version of the hook in DRuntime.
+1. Change the lowering in the compiler to use the new hook.
+1. Run a benchmark to measure the increase in performance generated by using the new hook.
+1. Remove the old hook from DRuntime.
+
+The hooks that are yet to be templated can be split into 2 categories:
+
+1. [`rt/aa.d`](https://github.com/dlang/dmd/blob/master/druntime/src/rt/aaA.d) implements associative arrays as language builtins.
+This module is made up of multiple hooks, all of them using `TypeInfo`.
+Therefore, this module is to be reimplemented using templates.
+The list of hooks for associative arrays is:
+
+    ```text
+    _aaApply
+    _aaApply2
+    _aaDelX
+    _aaEqual
+    _aaGetRvalueX
+    _aaGetX
+    _aaInX
+    _aaLen
+    _d_assocarrayliteralTX
+    ```
+
+1. Somewhat more independent hooks, which still have interdependencies.
+They are mostly implemented in [`rt/lifetime.d`](https://github.com/dlang/dmd/blob/master/druntime/src/rt/lifetime.d).
+A goal of this project is to remove this file and replace all its code with templated implementations.
+The full list is below:
+
+    ```text
+    _d_arrayliteralTX
+    _d_assocarrayliteralTX
+    _d_arraysetcapacity
+    _d_arraysetlengthiT
+    _d_arraysetlengthT
+    _d_arrayshrinkfit
+    _d_interface_cast
+    _d_isbaseof
+    _d_isbaseof2
+    _adEq2
+    ```
+
+## Resources
+
+- [Initial project proposal and discussion](https://github.com/dlang/project-ideas/issues/25)
+- [PRs converting some of the DRuntime hooks to templates](https://github.com/dlang/dmd/pulls?q=is%3Apr+author%3Ateodutu)
+- [Weekly reports regarding the earlier work](https://github.com/teodutu/saoc)
+- DConf presentations from [2022](https://www.youtube.com/watch?v=dsa8GWL6TUo) and [2024](https://www.youtube.com/live/FKI9M-KRjvA?t=24245) on the work on DRuntime hooks
+- [Instructions on how to build the reference compiler - DMD](https://wiki.dlang.org/Building_under_Posix#Building_DMD)