Improve performance when fetching Decls.

The current implementation in clangsharp_Cursor_getDecl to get a Decl is an N^2 algorithm;
getting a Decl for index X means looping through all the previous indices 0-(X-1)
first.

This is rather slow when dealing with hundreds of thousands of Decl instances, here's
a screenshot from Instruments showing 74% of the time spent in clangsharp_Cursor_getDecl:

<img width="921" height="348" alt="Screenshot 2026-01-07 at 12 47 26" src="https://github.com/user-attachments/assets/c96d5611-683e-4f0d-9878-cc551ba60c71" />

I had a few observations:

1. In my use case, I'll always iterate over all the Decls (once I start iterating).

2. There doesn't seem to be a way in native code to get the Decl given an index.

3. Storing the C++ iterator in C# to keep iterating on it is beyond my C++ knowledge
   (in particular any iterator lifetime management didn't look trivial).

So I implemented a way to get all the Decls and store them into a C# array directly,
so now the algorithm is 2N instead (iterate once to count the number of Decls, iterate
again to get them).

After this change, getting the Decls now takes up 0.0% (!):

<img width="930" height="400" alt="Screenshot 2026-01-07 at 12 47 14" src="https://github.com/user-attachments/assets/b40ac6d3-abb3-47c7-977c-884015b617ce" />

Also note the total time of the profiling session: 1.30 min vs 3.38 min.

Author: rolfbjarne

sources/ClangSharp.Interop/Extensions/CXCursor.cs

@@ -1834,6 +1834,8 @@ public static void DisposeOverriddenCursors(ReadOnlySpan<CXCursor> overridden)
 
     public readonly CXCursor GetDecl(uint index) => clangsharp.Cursor_getDecl(this, index);
 
+    public readonly bool GetDecls(CXCursor* cursors, uint count) => clangsharp.Cursor_getDecls(this, cursors, count);
+
     public readonly void GetDefinitionSpellingAndExtent(out string spelling, out uint startLine, out uint startColumn, out uint endLine, out uint endColumn)
     {
         fixed (uint* pStartLine = &startLine)

sources/ClangSharp.Interop/clangsharp/clangsharp.cs

@@ -6,7 +6,7 @@
 
 namespace ClangSharp.Interop;
 
-public static partial class @clangsharp
+public static unsafe partial class @clangsharp
 {
     [DllImport("libClangSharp", CallingConvention = CallingConvention.Cdecl, EntryPoint = "clangsharp_Cursor_getArgument", ExactSpelling = true)]
     public static extern CXCursor Cursor_getArgument(CXCursor C, [NativeTypeName("unsigned int")] uint i);
@@ -181,6 +181,9 @@ public static partial class @clangsharp
     [DllImport("libClangSharp", CallingConvention = CallingConvention.Cdecl, EntryPoint = "clangsharp_Cursor_getDecl", ExactSpelling = true)]
     public static extern CXCursor Cursor_getDecl(CXCursor C, [NativeTypeName("unsigned int")] uint i);
 
+    [DllImport("libClangSharp", CallingConvention = CallingConvention.Cdecl, EntryPoint = "clangsharp_Cursor_getDecls", ExactSpelling = true)]
+    public static extern bool Cursor_getDecls(CXCursor C, CXCursor* decls, [NativeTypeName("unsigned int")] uint count);
+
     [DllImport("libClangSharp", CallingConvention = CallingConvention.Cdecl, EntryPoint = "clangsharp_Cursor_getDeclKind", ExactSpelling = true)]
     public static extern CX_DeclKind Cursor_getDeclKind(CXCursor C);
 

sources/ClangSharp/Cursors/Decls/Decl.cs

@@ -35,7 +35,29 @@ private protected Decl(CXCursor handle, CXCursorKind expectedCursorKind, CX_Decl
         _attrs = LazyList.Create<Attr>(Handle.NumAttrs, (i) => TranslationUnit.GetOrCreate<Attr>(Handle.GetAttr(unchecked((uint)i))));
         _body = new ValueLazy<Stmt?>(() => !Handle.Body.IsNull ? TranslationUnit.GetOrCreate<Stmt>(Handle.Body) : null);
         _canonicalDecl = new ValueLazy<Decl>(() => TranslationUnit.GetOrCreate<Decl>(Handle.CanonicalCursor));
-        _decls = LazyList.Create<Decl>(Handle.NumDecls, (i) => TranslationUnit.GetOrCreate<Decl>(Handle.GetDecl(unchecked((uint)i))));
+        _decls = LazyList.Create<Decl>(Handle.NumDecls, (i) => TranslationUnit.GetOrCreate<Decl>(Handle.GetDecl(unchecked((uint)i))), (list) => {
+            var cursors = new CXCursor[list.Length];
+            bool success;
+            unsafe {
+                fixed (CXCursor* first = cursors) {
+                    success = Handle.GetDecls(first, unchecked((uint)list.Length));
+                }
+            }
+            if (success)
+            {
+                for (var i = 0; i < list.Length; i++)
+                {
+                    list[i] = TranslationUnit.GetOrCreate<Decl>(cursors[i]);
+                }
+            }
+            else
+            {
+                for (var i = 0; i < list.Length; i++)
+                {
+                    list[i] = TranslationUnit.GetOrCreate<Decl>(Handle.GetDecl(unchecked((uint)i)));
+                }
+            }
+        });
         _describedTemplate = new ValueLazy<TemplateDecl?>(() => {
             var describedTemplate = Handle.DescribedTemplate;
             return describedTemplate.IsNull ? null : TranslationUnit.GetOrCreate<TemplateDecl>(describedTemplate);

sources/ClangSharp/LazyList.cs

@@ -7,14 +7,14 @@ namespace ClangSharp;
 
 internal static class LazyList
 {
-    public static LazyList<T> Create<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)] T>(int count, Func<int, T> valueFactory)
+    public static LazyList<T> Create<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)] T>(int count, Func<int, T> valueFactory, Action<T[]>? allValuesFactory = null)
         where T : class
     {
         if (count <= 0)
         {
             return LazyList<T>.Empty;
         }
-        return new LazyList<T>(count, valueFactory);
+        return new LazyList<T>(count, valueFactory, allValuesFactory);
     }
 
     public static LazyList<T, TBase> Create<T, [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)] TBase>(LazyList<TBase> list, int skip = -1, int take = -1)

sources/ClangSharp/LazyList`1.cs

@@ -12,13 +12,15 @@ internal sealed class LazyList<[DynamicallyAccessedMembers(DynamicallyAccessedMe
 {
     internal readonly T[] _items;
     internal readonly Func<int, T> _valueFactory;
+    internal readonly Action<T[]>? _allValuesFactory;
 
     public static readonly LazyList<T> Empty = new LazyList<T>(0, _ => null!);
 
-    public LazyList(int count, Func<int, T> valueFactory)
+    public LazyList(int count, Func<int, T> valueFactory, Action<T[]>? allValuesFactory = null)
     {
         _items = (count <= 0) ? [] : new T[count];
         _valueFactory = valueFactory;
+        _allValuesFactory = allValuesFactory;
     }
 
     public T this[int index]
@@ -30,8 +32,16 @@ public T this[int index]
 
             if (item is null)
             {
-                item = _valueFactory(index);
-                items[index] = item;
+                if (_allValuesFactory is not null)
+                {
+                    _allValuesFactory(_items);
+                    item = _items[index];
+                }
+                else
+                {
+                    item = _valueFactory(index);
+                    items[index] = item;
+                }
             }
 
             return item;
@@ -56,14 +66,7 @@ public void CopyTo(T[] array, int arrayIndex)
 
         for (var i = 0; i < items.Length; i++)
         {
-            var currentItem = items[i];
-
-            if (currentItem is null)
-            {
-                currentItem = _valueFactory(i);
-                items[i] = currentItem;
-            }
-
+            var currentItem = this[i];
             array[arrayIndex + i] = currentItem;
         }
     }
@@ -76,14 +79,7 @@ public int IndexOf(T item)
 
         for (var i = 0; i < items.Length; i++)
         {
-            var currentItem = items[i];
-
-            if (currentItem is null)
-            {
-                currentItem = _valueFactory(i);
-                items[i] = currentItem;
-            }
-
+            var currentItem = this[i];
             if (EqualityComparer<T>.Default.Equals(currentItem, item))
             {
                 return i;

sources/libClangSharp/ClangSharp.cpp

@@ -943,6 +943,28 @@ CXType clangsharp_Cursor_getDeclaredReturnType(CXCursor C) {
     return MakeCXType(QualType(), getCursorTU(C));
 }
 
+bool clangsharp_Cursor_getDecls(CXCursor C, CXCursor* decls, unsigned count) {
+    if (isDeclOrTU(C.kind)) {
+        const Decl* D = getCursorDecl(C);
+
+        if (const DeclContext* DC = dyn_cast<DeclContext>(D)) {
+            unsigned n = 0;
+
+            for (auto decl : DC->decls()) {
+                if (n == count) {
+                    return false;
+                }
+                decls[n] = MakeCXCursor(decl, getCursorTU(C));
+                n++;
+            }
+
+            return n == count;
+        }
+    }
+
+    return false;
+}
+
 CXCursor clangsharp_Cursor_getDecl(CXCursor C, unsigned i) {
     if (isDeclOrTU(C.kind)) {
         const Decl* D = getCursorDecl(C);

sources/libClangSharp/ClangSharp.h

@@ -341,6 +341,8 @@ CLANGSHARP_LINKAGE CXType clangsharp_Cursor_getDeclaredReturnType(CXCursor C);
 
 CLANGSHARP_LINKAGE CXCursor clangsharp_Cursor_getDecl(CXCursor C, unsigned i);
 
+CLANGSHARP_LINKAGE bool clangsharp_Cursor_getDecls(CXCursor C, CXCursor* decls, unsigned count);
+
 CLANGSHARP_LINKAGE CX_DeclKind clangsharp_Cursor_getDeclKind(CXCursor C);
 
 CLANGSHARP_LINKAGE CXCursor clangsharp_Cursor_getDecomposedDecl(CXCursor C);

tests/ClangSharp.UnitTests/CXCursor.cs

@@ -10,6 +10,7 @@ public class CXCursorTest : TranslationUnitTest
     [Test]
     public void AttrKindSpelling()
     {
+        AssertNeedNewClangSharp();
 
         var inputContents =
     $$"""

tests/ClangSharp.UnitTests/CursorTests/DeclTest.cs

@@ -15,6 +15,8 @@ public sealed class DeclTest : TranslationUnitTest
     [TestCase("public", CX_CXXPublic)]
     public void AccessSpecDeclTest(string accessSpecifier, CX_CXXAccessSpecifier expectedAccessSpecifier)
     {
+        AssertNeedNewClangSharp();
+
         var inputContents = $@"struct MyStruct
 {{
 {accessSpecifier}:
@@ -32,6 +34,8 @@ public void AccessSpecDeclTest(string accessSpecifier, CX_CXXAccessSpecifier exp
     [Test]
     public void ClassTemplateDeclTest()
     {
+        AssertNeedNewClangSharp();
+
         var inputContents = $@"template<class T>
 class MyClass
 {{
@@ -51,6 +55,8 @@ class MyClass
     [Test]
     public void ClassTemplatePartialSpecializationDeclTest()
     {
+        AssertNeedNewClangSharp();
+
         var inputContents = $@"template<class T, class U>
 class MyClass
 {{
@@ -78,6 +84,8 @@ class MyClass<int, U>
     [Test]
     public void TemplateParameterPackTest()
     {
+        AssertNeedNewClangSharp();
+
         var inputContents = $@"template<class... Types>
 class tuple;