2025: Add "Translate DRuntime Hooks to Templates" project

gsoc-2025/template-hooks.md

@@ -0,0 +1,110 @@
+---
+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 simplifies 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 than 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 according to the types of its arguments at compile time.
+
+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.
+Associative arrays are defined as an opaque structure called [`Impl`](https://github.com/dlang/dmd/blob/da0fc14189d6614df48cbbf1f5bbf7fc5f93b5f7/druntime/src/rt/aaA.d#L50-L172).
+It receives a `TypeInfo` argument in its constructor.
+This structure is accessed via the runtime hooks listed below.
+The plan for this direction is the following:
+    1. Template the hooks below and temporarily extract the `TypeInfo` structure required by `Impl` from the template arguments using [`typeid`](https://dlang.org/spec/expression.html#TypeidExpression).
+    Each hook will require changes to DRuntime and the compiler.
+    1. Template the `Impl` structure and modify the previously templated hooks to use the template arguments itself instead of `TypeInfo`.
+
+    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.
+Each hook can be handled individually and separately.
+There was previous work on `_d_arrayliteralTX` so it might be a good starting point.
+Another promising starting point are `_d_arrayset{capacity,lengthT,lengthiT}` or `_d_arrayappendcTX`.
+The latter three already have wrapper template hooks that call the functions from `rt/lifetime.d`.
+What is needed in their case is to fully move the underlying implementation to the template hooks.
+The full list of hooks is below:
+
+    ```text
+    _d_arraysetcapacity
+    _d_arraysetlengthiT
+    _d_arraysetlengthT
+    _d_arrayshrinkfit
+    _d_arrayappendcTX
+    _d_arrayliteralTX
+    _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)