Skip to content

Commit 3fadc2c

Browse files
nyamsprodnyamsprod
committed
Improve public API and documentation
1 parent 6ef7107 commit 3fadc2c

File tree

8 files changed

+108
-76
lines changed

8 files changed

+108
-76
lines changed

‎CHANGELOG.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,36 @@
22

33
All Notable changes to `bakame/stackwatch` will be documented in this file.
44

5+
## [Next - Qandala](https://github.com/bakame-php/stackwatch/compare/0.16.1...main) - 2026-XX-XX
6+
7+
### Added
8+
9+
- **BC BREAK:** Rename `stack_cdump` to `stack_call_dump`
10+
- **BC BREAK:** Rename `stack_bdump` to `stack_bench_dump`
11+
- **BC BREAK:** Rename `stack_rdump` to `stack_report_dump`
12+
- **BC BREAK:** Rename `stack_cdd` to `stack_call_dd`
13+
- **BC BREAK:** Rename `stack_bdd` to `stack_bench_dd`
14+
- **BC BREAK:** Rename `stack_rdd` to `stack_report_dd`
15+
- **BC BREAK:** Rename `Stack::dumpCall` to `Stack::callDump`
16+
- **BC BREAK:** Rename `Stack::ddCall` to `Stack::callDd`
17+
- **BC BREAK:** Rename `Stack::dumpReport` to `Stack::reportDump`
18+
- **BC BREAK:** Rename `Stack::ddReport` to `Stack::reportDd`
19+
- **BC BREAK:** Rename `Stack::benchmark` to `Stack::bench`
20+
- **BC BREAK:** Rename `Stack::dumpBenchmark` to `Stack::benchDump`
21+
- **BC BREAK:** Rename `Stack::ddBenchmark` to `Stack::benchDd`
22+
23+
### Fixed
24+
25+
- Call Location calculation to include the correct call start path.
26+
27+
### Deprecated
28+
29+
- None
30+
31+
### Remove
32+
33+
- None
34+
535
## [0.16.1 - Pointe-Noire](https://github.com/bakame-php/stackwatch/compare/0.16.0...0.16.1) - 2026-02-07
636

737
### Added

‎docs/1.0/stack.md‎

Lines changed: 18 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -110,22 +110,21 @@ You can learn more about this `Statistics` and `AggregatedMetrics` in the [build
110110

111111
For quick inspection:
112112

113-
- `stack_cdump()` → dumps span/metrics, continues execution
114-
- `stack_cdd()` → dumps span/metrics, halts execution
115-
- `stack_rdump()` → dumps detailed report, continues execution
116-
- `stack_rdd()` → dumps detailed report, halts execution
117-
- `stack_bdump()` → dumps summary metrics, continues execution
118-
- `stack_bdd()` → dumps summary metrics, halts execution
119-
120-
121-
| Function | Returns | Dumps? | Halts? |
122-
|------------------|-----------|--------|--------|
123-
| `stack_call()` | `Result` | ❌ | ❌ |
124-
| `stack_cdump()` | `Result` | ✅ | ❌ |
125-
| `stack_cdd()` | `never` | ✅ | ✅ |
126-
| `stack_report()` | `Report` | ❌ | ❌ |
127-
| `stack_rdump()` | `Report` | ✅ | ❌ |
128-
| `stack_rdd()` | `never` | ✅ | ✅ |
129-
| `stack_bench()` | `Metrics` | ❌ | ❌ |
130-
| `stack_bdump()` | `Metrics` | ✅ | ❌ |
131-
| `stack_bdd()` | `never` | ✅ | ✅ |
113+
- `stack_dump_call()` → dumps span/metrics, continues execution
114+
- `stack_dd_call()` → dumps span/metrics, halts execution
115+
- `stack_dump_report()` → dumps detailed report, continues execution
116+
- `stack_dd_report()` → dumps detailed report, halts execution
117+
- `stack_dump_bench()` → dumps summary metrics, continues execution
118+
- `stack_dd_bench()` → dumps summary metrics, halts execution
119+
120+
| Function | Returns | Dumps? | Halts? |
121+
|-----------------------|-----------|--------|--------|
122+
| `stack_call()` | `Result` | ❌ | ❌ |
123+
| `stack_call_dump()` | `Result` | ✅ | ❌ |
124+
| `stack_call_dd()` | `never` | ✅ | ✅ |
125+
| `stack_report()` | `Report` | ❌ | ❌ |
126+
| `stack_report_dump()` | `Report` | ✅ | ❌ |
127+
| `stack_report_dd()` | `never` | ✅ | ✅ |
128+
| `stack_bench()` | `Metrics` | ❌ | ❌ |
129+
| `stack_bench_dump()` | `Metrics` | ✅ | ❌ |
130+
| `stack_bench_dd()` | `never` | ✅ | ✅ |

‎src/CallLocation.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
*/
2222
final class CallLocation implements JsonSerializable
2323
{
24-
private const BACKTRACE_LIMIT = 4;
24+
private const BACKTRACE_LIMIT = 5;
2525

2626
public function __construct(
2727
public readonly ?string $path = null,

‎src/Console/UnitOfWork.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,7 @@ public function run(): void
282282
$this->runAt = new DateTimeImmutable('now', new DateTimeZone('UTC'));
283283
$this->result = match ($this->profile->type) {
284284
null => Stack::report($callback, $this->profile->iterations, $this->profile->warmup),
285-
default => Stack::benchmark($callback, $this->profile->iterations, $this->profile->warmup, $this->profile->type),
285+
default => Stack::bench($callback, $this->profile->iterations, $this->profile->warmup, $this->profile->type),
286286
};
287287
}
288288
}

‎src/Stack.php‎

Lines changed: 41 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
use Bakame\Stackwatch\Exporter\CallbackDumper;
88
use Bakame\Stackwatch\Exporter\ViewExporter;
9+
use Generator;
910
use Throwable;
1011

1112
use function gc_collect_cycles;
@@ -69,7 +70,7 @@ public static function call(callable $callback, ?string $label = null): Result
6970
*
7071
* @throws InvalidArgument|Throwable
7172
*/
72-
public static function dumpCall(callable $callback, ?string $label = null): Result
73+
public static function callDump(callable $callback, ?string $label = null): Result
7374
{
7475
$result = self::call($callback, $label);
7576
$result->span->dump();
@@ -84,26 +85,11 @@ public static function dumpCall(callable $callback, ?string $label = null): Resu
8485
*
8586
* @throws InvalidArgument|Throwable
8687
*/
87-
public static function ddCall(callable $callback, ?string $label = null): never
88+
public static function callDd(callable $callback, ?string $label = null): never
8889
{
8990
self::call($callback, $label)->span->dd();
9091
}
9192

92-
/**
93-
* Returns aggregated metrics associated with the callback.
94-
*
95-
* The aggregation mode (average, median, …) is controlled by $aggregatorMode.
96-
*
97-
* @param int<0, max> $warmup
98-
* @param int<1, max> $iterations
99-
*
100-
* @throws InvalidArgument|Throwable
101-
*/
102-
public static function benchmark(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): AggregatedMetrics
103-
{
104-
return self::report($callback, $iterations, $warmup)->column($type);
105-
}
106-
10793
/**
10894
* Returns the metrics associated with the callback.
10995
*
@@ -117,12 +103,14 @@ public static function report(callable $callback, int $iterations = 1, int $warm
117103
self::assertItCanBeRun($iterations, $warmup);
118104
self::warmup($warmup, $callback);
119105
gc_collect_cycles();
120-
$metrics = [];
121-
for ($i = 0; $i < $iterations; ++$i) {
122-
$metrics[] = self::call($callback)->span->metrics;
123-
}
124106

125-
return Report::fromMetrics(...$metrics);
107+
return Report::fromMetrics(
108+
...(function () use ($iterations, $callback): Generator {
109+
for ($i = 0; $i < $iterations; ++$i) {
110+
yield self::call($callback)->span->metrics;
111+
}
112+
})()
113+
);
126114
}
127115

128116
/**
@@ -133,7 +121,7 @@ public static function report(callable $callback, int $iterations = 1, int $warm
133121
*
134122
* @throws Throwable
135123
*/
136-
public static function dumpReport(callable $callback, int $iterations = 1, int $warmup = 0): Report
124+
public static function reportDump(callable $callback, int $iterations = 1, int $warmup = 0): Report
137125
{
138126
$stats = self::report($callback, $iterations, $warmup);
139127

@@ -146,6 +134,32 @@ public static function dumpReport(callable $callback, int $iterations = 1, int $
146134
return $stats;
147135
}
148136

137+
/**
138+
* Profile a callable, dump the stats to console and die.
139+
*
140+
* @param int<1, max> $iterations
141+
* @param int<0, max> $warmup
142+
*/
143+
public static function reportDd(callable $callback, int $iterations = 1, int $warmup = 0): never
144+
{
145+
CallbackDumper::dd(fn (): Report => self::reportDump($callback, $iterations, $warmup));
146+
}
147+
148+
/**
149+
* Returns aggregated metrics associated with the callback.
150+
*
151+
* The aggregation mode (average, median, …) is controlled by $aggregatorMode.
152+
*
153+
* @param int<0, max> $warmup
154+
* @param int<1, max> $iterations
155+
*
156+
* @throws InvalidArgument|Throwable
157+
*/
158+
public static function bench(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): AggregatedMetrics
159+
{
160+
return self::report($callback, $iterations, $warmup)->column($type);
161+
}
162+
149163
/**
150164
* Profile a callable and dump the stats to console.
151165
*
@@ -154,9 +168,9 @@ public static function dumpReport(callable $callback, int $iterations = 1, int $
154168
*
155169
* @throws Throwable
156170
*/
157-
public static function dumpBenchmark(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): AggregatedMetrics
171+
public static function benchDump(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): AggregatedMetrics
158172
{
159-
$stats = self::benchmark($callback, $iterations, $warmup, $type);
173+
$stats = self::bench($callback, $iterations, $warmup, $type);
160174

161175
(new ViewExporter())->exportStack(
162176
$stats,
@@ -173,19 +187,8 @@ public static function dumpBenchmark(callable $callback, int $iterations = 1, in
173187
* @param int<1, max> $iterations
174188
* @param int<0, max> $warmup
175189
*/
176-
public static function ddReport(callable $callback, int $iterations = 1, int $warmup = 0): never
177-
{
178-
CallbackDumper::dd(fn (): Report => self::dumpReport($callback, $iterations, $warmup));
179-
}
180-
181-
/**
182-
* Profile a callable, dump the stats to console and die.
183-
*
184-
* @param int<1, max> $iterations
185-
* @param int<0, max> $warmup
186-
*/
187-
public static function ddBenchmark(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): never
190+
public static function benchDd(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): never
188191
{
189-
CallbackDumper::dd(fn (): AggregatedMetrics => self::dumpBenchmark($callback, $iterations, $warmup, $type));
192+
CallbackDumper::dd(fn (): AggregatedMetrics => self::benchDump($callback, $iterations, $warmup, $type));
190193
}
191194
}

‎src/StackTest.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ public function it_can_return_each_metrics_separately(): void
2828
return 'end';
2929
};
3030

31-
$metrics = Stack::benchmark($callback, iterations: 2, warmup: 3);
31+
$metrics = Stack::bench($callback, iterations: 2, warmup: 3);
3232

3333
self::assertGreaterThanOrEqual(0, $metrics->executionTime);
3434
self::assertGreaterThanOrEqual(0, $metrics->cpuTime);
@@ -43,6 +43,6 @@ public function it_fails_to_return_the_metrics_on_invalid_iteration_argument():
4343
{
4444
$this->expectException(InvalidArgument::class);
4545

46-
Stack::benchmark(fn () => null, 0); /* @phpstan-ignore-line */
46+
Stack::bench(fn () => null, 0); /* @phpstan-ignore-line */
4747
}
4848
}

‎src/Version.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@
1111
final class Version implements Stringable
1212
{
1313
private const NAME = 'stackwatch';
14-
private const VERSION_ID = '0.16.0';
15-
private const VERSION_NAME = 'Pointe-Noire';
14+
private const VERSION_ID = '0.17.0';
15+
private const VERSION_NAME = 'Qandala';
1616
private const AUTHOR = 'Ignace Nyamagana Butera';
1717

1818
public static function name(): string

‎src/functions.php‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ function stack_call(callable $callback, ?string $label = null): Result
2929
*
3030
* @throws Throwable
3131
*/
32-
function stack_cdump(callable $callback, ?string $label = null): Result
32+
function stack_call_dump(callable $callback, ?string $label = null): Result
3333
{
34-
return Stack::dumpCall($callback, $label);
34+
return Stack::callDump($callback, $label);
3535
}
3636

3737
/**
@@ -43,9 +43,9 @@ function stack_cdump(callable $callback, ?string $label = null): Result
4343
*
4444
* @throws Throwable
4545
*/
46-
function stack_cdd(callable $callback, ?string $label = null): never
46+
function stack_call_dd(callable $callback, ?string $label = null): never
4747
{
48-
Stack::ddCall($callback, $label);
48+
Stack::callDd($callback, $label);
4949
}
5050

5151
/**
@@ -71,9 +71,9 @@ function stack_report(callable $callback, int $iterations = 1, int $warmup = 0):
7171
*
7272
* @throws Throwable
7373
*/
74-
function stack_rdump(callable $callback, int $iterations = 1, int $warmup = 0): Report
74+
function stack_report_dump(callable $callback, int $iterations = 1, int $warmup = 0): Report
7575
{
76-
return Stack::dumpReport($callback, $iterations, $warmup);
76+
return Stack::reportDump($callback, $iterations, $warmup);
7777
}
7878

7979
/**
@@ -82,9 +82,9 @@ function stack_rdump(callable $callback, int $iterations = 1, int $warmup = 0):
8282
* @param int<1, max> $iterations
8383
* @param int<0, max> $warmup
8484
*/
85-
function stack_rdd(callable $callback, int $iterations = 1, int $warmup = 0): never
85+
function stack_report_dd(callable $callback, int $iterations = 1, int $warmup = 0): never
8686
{
87-
Stack::ddReport($callback, $iterations, $warmup);
87+
Stack::reportDd($callback, $iterations, $warmup);
8888
}
8989

9090
/**
@@ -97,7 +97,7 @@ function stack_rdd(callable $callback, int $iterations = 1, int $warmup = 0): ne
9797
*/
9898
function stack_bench(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): AggregatedMetrics
9999
{
100-
return Stack::benchmark($callback, $iterations, $warmup, $type);
100+
return Stack::bench($callback, $iterations, $warmup, $type);
101101
}
102102

103103
/**
@@ -110,9 +110,9 @@ function stack_bench(callable $callback, int $iterations = 1, int $warmup = 0, A
110110
*
111111
* @throws Throwable
112112
*/
113-
function stack_bdump(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): AggregatedMetrics
113+
function stack_bench_dump(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): AggregatedMetrics
114114
{
115-
return Stack::dumpBenchmark($callback, $iterations, $warmup, $type);
115+
return Stack::benchDump($callback, $iterations, $warmup, $type);
116116
}
117117

118118
/**
@@ -121,7 +121,7 @@ function stack_bdump(callable $callback, int $iterations = 1, int $warmup = 0, A
121121
* @param int<1, max> $iterations
122122
* @param int<0, max> $warmup
123123
*/
124-
function stack_bdd(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): never
124+
function stack_bench_dd(callable $callback, int $iterations = 1, int $warmup = 0, AggregationType $type = AggregationType::Average): never
125125
{
126-
Stack::ddBenchmark($callback, $iterations, $warmup, $type);
126+
Stack::benchDd($callback, $iterations, $warmup, $type);
127127
}

0 commit comments

Comments
 (0)