🤖 Merge PR DefinitelyTyped#72240 Improve the frida-gum Profiler typings by @oleavr

Author: oleavr

types/frida-gum/frida-gum-tests.ts

@@ -454,3 +454,10 @@ const moduleObserver = Process.attachModuleObserver({
     },
 });
 moduleObserver.detach();
+
+// $ExpectType Profiler
+const profiler = new Profiler();
+const sampler = new BusyCycleSampler();
+for (const e of Process.getModuleByName("libc.so").enumerateExports().filter(e => e.type === "function")) {
+    profiler.instrument(e.address, sampler);
+}

types/frida-gum/index.d.ts

@@ -4640,11 +4640,36 @@ declare namespace Cloak {
     function hasFileDescriptor(fd: number): boolean;
 }
 
+/**
+ * Simple worst-case profiler built on top of Interceptor.
+ *
+ * Unlike a conventional profiler, which samples call stacks at a certain
+ * frequency, you decide the exact functions that you're interested in
+ * profiling.
+ *
+ * When any of those functions gets called, the profiler grabs a sample on
+ * entry, and another one upon return. It then subtracts the two, to compute how
+ * expensive the call was. If the resulting value is greater than what it's seen
+ * previously for the specific function, that value becomes its new worst-case.
+ *
+ * Whenever a new worst-case has been discovered, it isn't necessarily enough to
+ * know that most of the time/cycles/etc. was spent by a specific function. That
+ * function may only be slow with certain input arguments, for example.
+ *
+ * This is a situation where you can pass in `ProfilerInstrumentCallbacks` to
+ * implement a `describe()` callback for the specific function. Your callback
+ * should capture relevant context from the argument list and/or other state,
+ * and return a string that describes the new worst-case that was just
+ * discovered.
+ *
+ * When you later decide to call `generateReport()`, you'll find your computed
+ * descriptions embedded in each worst-case entry.
+ */
 declare class Profiler {
     /**
      * Starts instrumenting the specified function using the specified sampler.
      */
-    instrument(functionAddress: NativePointerValue, sampler: Sampler, callbacks: ProfilerInstrumentCallbacks): void;
+    instrument(functionAddress: NativePointerValue, sampler: Sampler, callbacks?: ProfilerInstrumentCallbacks): void;
 
     /**
      * Generates an XML report from the live profiler state. May be called at