diff --git a/README.md b/README.md index eb67ad2..cdff282 100644 --- a/README.md +++ b/README.md @@ -50,35 +50,35 @@ echo doSomething(new NullProfiler()); ## Useful features -### Snapshots +### Take snapshot -If you need to **measure the current values**, just call the `snapshot` method on the [`Profiling`](./src/Profiling.php). +If you need to **measure the current values**, just call the `takeSnapshot` method on the [`Profiling`](./src/Profiling.php), or a [profiler](./src/ProfilerInterface.php). ```php namespace PetrKnap\Profiler; $profiling = Profiling::start(); // do something -$profiling->snapshot(); +$profiling->takeSnapshot(); // do something more $profile = $profiling->finish(); printf('There are %d memory usage records.', count($profile->getMemoryUsages())); ``` -If you want to automate it then use a [snapshot on tick](#snapshot-on-tick). +If you want to automate it then [take snapshot on tick](#take-snapshot-on-tick). Or you can use a more practical [cascade profiling](#cascade-profiling). -#### Snapshot on tick +#### Take snapshot on tick -For greater precision, you can force **snapshot on each `N` tick**. +For greater precision, you can take **snapshot on each `N` tick**. ```php declare(ticks=2); // this declaration is important (N=2) namespace PetrKnap\Profiler; -$profiling = Profiling::start(snapshotOnTick: true); +$profiling = Profiling::start(takeSnapshotOnTick: true); (fn () => 'something')(); $profile = $profiling->finish(); diff --git a/src/Exception/ProfilerCouldNotSnapshotOutsideParentProfile.php b/src/Exception/ProfilerCouldNotSnapshotOutsideParentProfile.php deleted file mode 100644 index aefcc7a..0000000 --- a/src/Exception/ProfilerCouldNotSnapshotOutsideParentProfile.php +++ /dev/null @@ -1,11 +0,0 @@ -state = ProfileState::Created; - $this->isSnapshotingOnTick = $snapshotOnTick ? false : null; + $this->isTakingSnapshotOnTick = $takeSnapshotOnTick ? false : null; $this->timeBefore = OptionalFloat::empty(); $this->memoryUsageBefore = OptionalInt::empty(); $this->timeAfter = OptionalFloat::empty(); @@ -56,7 +56,7 @@ public function __construct( public function __destruct() { - $this->unregisterTickSnapshot(); + $this->unregisterTickHandlers(); } public function getState(): ProfileState @@ -77,7 +77,7 @@ public function start(): void $this->timeBefore = OptionalFloat::of(microtime(as_float: true)); $this->memoryUsageBefore = OptionalInt::of(memory_get_usage(real_usage: true)); - $this->registerTickSnapshot(); + $this->registerTickHandlers(); } /** @@ -85,7 +85,7 @@ public function start(): void */ public function finish(): void { - $this->unregisterTickSnapshot(); + $this->unregisterTickHandlers(); if ($this->state !== ProfileState::Started) { throw new Exception\ProfileCouldNotBeFinished(); @@ -99,23 +99,23 @@ public function finish(): void /** * @throws Exception\ProfileCouldNotRegisterTickHandler */ - public function registerTickSnapshot(): void + public function registerTickHandlers(): void { - if ($this->isSnapshotingOnTick === false) { - register_tick_function([$this, 'snapshot']) or throw new Exception\ProfileCouldNotRegisterTickHandler(); - $this->isSnapshotingOnTick = true; + if ($this->isTakingSnapshotOnTick === false) { + register_tick_function([$this, 'takeSnapshot']) or throw new Exception\ProfileCouldNotRegisterTickHandler(); + $this->isTakingSnapshotOnTick = true; } } - public function unregisterTickSnapshot(): void + public function unregisterTickHandlers(): void { - if ($this->isSnapshotingOnTick === true) { - unregister_tick_function([$this, 'snapshot']); - $this->isSnapshotingOnTick = false; + if ($this->isTakingSnapshotOnTick === true) { + unregister_tick_function([$this, 'takeSnapshot']); + $this->isTakingSnapshotOnTick = false; } } - public function snapshot(): void + public function takeSnapshot(): void { $this->memoryUsages[sprintf(self::MICROTIME_FORMAT, microtime(as_float: true))] = memory_get_usage(real_usage: true); } @@ -145,8 +145,7 @@ public function setOutput(mixed $output): void public function getOutput(): mixed { - /** @var TOutput */ - return $this->outputOption->orElseThrow()->orElse(null); + return $this->outputOption->orElseThrow()->orElse(null); // @phpstan-ignore return.type } public function addChild(ProfileInterface $child): void diff --git a/src/Profiler.php b/src/Profiler.php index 9a8be32..68e354f 100644 --- a/src/Profiler.php +++ b/src/Profiler.php @@ -6,22 +6,20 @@ /* final */class Profiler implements ProfilerInterface { - /** - * @param bool $snapshotOnTick if true, it will do snapshot on each tick - */ public function __construct( - private readonly bool $snapshotOnTick = Profile::DO_NOT_SNAPSHOT_ON_TICK, + private readonly bool $takeSnapshotOnTick = Profile::DO_NOT_TAKE_SNAPSHOT_ON_TICK, /** - * @deprecated + * @deprecated backward compatibility with old named argument calls + * * @todo remove it */ - private readonly bool $listenToTicks = Profile::DO_NOT_SNAPSHOT_ON_TICK, + private readonly bool $listenToTicks = Profile::DO_NOT_TAKE_SNAPSHOT_ON_TICK, ) { } public function profile(callable $callable): ProcessableProfileInterface & ProfileWithOutputInterface { - $profiling = Profiling::start($this->snapshotOnTick, $this->listenToTicks); + $profiling = Profiling::start($this->takeSnapshotOnTick, $this->listenToTicks); $output = $callable(Profiling::createNestedProfiler($profiling)); /** @var Profile $profile */ $profile = $profiling->finish(); @@ -30,8 +28,8 @@ public function profile(callable $callable): ProcessableProfileInterface & Profi return $profile; // @phpstan-ignore return.type } - public function snapshot(): void + public function takeSnapshot(): void { - throw new Exception\ProfilerCouldNotSnapshotOutsideParentProfile(); + throw new Exception\ProfilerCouldNotTakeSnapshotOutsideParentProfile(); } } diff --git a/src/ProfilerInterface.php b/src/ProfilerInterface.php index 21ceb51..567a601 100644 --- a/src/ProfilerInterface.php +++ b/src/ProfilerInterface.php @@ -16,7 +16,7 @@ interface ProfilerInterface public function profile(callable $callable): ProcessableProfileInterface & ProfileWithOutputInterface; /** - * @throws Exception\ProfilerCouldNotSnapshotOutsideParentProfile + * @throws Exception\ProfilerCouldNotTakeSnapshotOutsideParentProfile */ - public function snapshot(): void; + public function takeSnapshot(): void; } diff --git a/src/Profiling.php b/src/Profiling.php index f610f2b..041391e 100644 --- a/src/Profiling.php +++ b/src/Profiling.php @@ -11,35 +11,36 @@ final class Profiling */ private function __construct( private readonly Profile $profile, - private readonly bool $snapshotOnTick, + private readonly bool $takeSnapshotOnTick, ) { } /** - * @param bool $snapshotOnTick if true, it will do snapshot on each tick + * @param bool $takeSnapshotOnTick if true, it will do snapshot on each tick */ public static function start( - bool $snapshotOnTick = Profile::DO_NOT_SNAPSHOT_ON_TICK, + bool $takeSnapshotOnTick = Profile::DO_NOT_TAKE_SNAPSHOT_ON_TICK, /** - * @deprecated + * @deprecated backward compatibility with old named argument calls + * * @todo remove it */ - bool $listenToTicks = Profile::DO_NOT_SNAPSHOT_ON_TICK, + bool $listenToTicks = Profile::DO_NOT_TAKE_SNAPSHOT_ON_TICK, ): self { - $profile = new Profile($listenToTicks || $snapshotOnTick); + $profile = new Profile($listenToTicks || $takeSnapshotOnTick); $profile->start(); - return new self($profile, $listenToTicks || $snapshotOnTick); + return new self($profile, $listenToTicks || $takeSnapshotOnTick); } /** * @throws Exception\ProfilingHasBeenAlreadyFinished */ - public function snapshot(): void + public function takeSnapshot(): void { $this->checkProfileState(); - $this->profile->snapshot(); + $this->profile->takeSnapshot(); } /** @@ -59,7 +60,7 @@ public function finish(): ProfileInterface */ public static function createNestedProfiler(Profiling $profiling): ProfilerInterface { - return new class ($profiling->profile, $profiling->snapshotOnTick) extends Profiler { + return new class ($profiling->profile, $profiling->takeSnapshotOnTick) extends Profiler { /** * @param Profile $parentProfile */ @@ -68,7 +69,7 @@ public function __construct( bool $snapshotOnTick, ) { parent::__construct( - snapshotOnTick: $snapshotOnTick, + takeSnapshotOnTick: $snapshotOnTick, ); } @@ -78,23 +79,23 @@ public function profile(callable $callable): ProcessableProfileInterface & Profi throw new Exception\ParentProfileIsNotStarted(); } - $this->parentProfile->unregisterTickSnapshot(); + $this->parentProfile->unregisterTickHandlers(); try { $profile = parent::profile($callable); $this->parentProfile->addChild($profile); return $profile; } finally { - $this->parentProfile->registerTickSnapshot(); + $this->parentProfile->registerTickHandlers(); } } - public function snapshot(): void + public function takeSnapshot(): void { if ($this->parentProfile->getState() !== ProfileState::Started) { - throw new Exception\ProfilerCouldNotSnapshotOutsideParentProfile(); + throw new Exception\ProfilerCouldNotTakeSnapshotOutsideParentProfile(); } - $this->parentProfile->snapshot(); + $this->parentProfile->takeSnapshot(); } }; } diff --git a/tests/NullProfilerTest.php b/tests/NullProfilerTest.php index 33058f4..d3d82c6 100644 --- a/tests/NullProfilerTest.php +++ b/tests/NullProfilerTest.php @@ -42,11 +42,11 @@ public function testProfileDoesNotRunProcessorAndReturnsCallablesOutput(): void self::assertSame('output', $output); } - public function testSnapshotDoesNotThrow(): void + public function testTakeSnapshotDoesNotThrow(): void { $profiler = new NullProfiler(); - $profiler->snapshot(); + $profiler->takeSnapshot(); self::assertTrue(true); } diff --git a/tests/ProfileTest.php b/tests/ProfileTest.php index 7bf7786..cde1e09 100644 --- a/tests/ProfileTest.php +++ b/tests/ProfileTest.php @@ -26,20 +26,20 @@ public function testAddsChildren(): void self::assertSame([$child1, $child2], $parent->getChildren()); } - #[DataProvider('dataSnapshotsOnTick')] - public function testSnapshotsOnTick(bool|null $shouldItSnapshot): void + #[DataProvider('dataTakesSnapshotOnTick')] + public function testTakesSnapshotOnTick(bool|null $shouldItTakeSnapshot): void { - $profile = $shouldItSnapshot === null ? new Profile() : new Profile(snapshotOnTick: $shouldItSnapshot); + $profile = $shouldItTakeSnapshot === null ? new Profile() : new Profile(takeSnapshotOnTick: $shouldItTakeSnapshot); $profile->start(); for ($i = 0; $i < 5; $i++) { $i = (fn (int $i): int => $i)($i); } $profile->finish(); - self::assertCount($shouldItSnapshot === true ? 9 : 2, $profile->getMemoryUsages()); + self::assertCount($shouldItTakeSnapshot === true ? 9 : 2, $profile->getMemoryUsages()); } - public static function dataSnapshotsOnTick(): array + public static function dataTakesSnapshotOnTick(): array { return [ 'default' => [null], diff --git a/tests/ProfilerTest.php b/tests/ProfilerTest.php index 321b7f0..0af7e46 100644 --- a/tests/ProfilerTest.php +++ b/tests/ProfilerTest.php @@ -38,21 +38,21 @@ public function testReturnsCallablesOutput(): void self::assertSame('output', $profile->getOutput()); } - public function testSnapshotsOnParentProfile(): void + public function testTakesSnapshotOnParentProfile(): void { $profiler = new Profiler(); - $profile = $profiler->profile(static fn (ProfilerInterface $profiler) => $profiler->snapshot()); + $profile = $profiler->profile(static fn (ProfilerInterface $profiler) => $profiler->takeSnapshot()); self::assertCount(2 + 1, $profile->getMemoryUsages()); } - public function testSnapshotsThrowsOutsideProfile(): void + public function testTakeSnapshotThrowsOutsideParentProfile(): void { $profiler = new Profiler(); - self::expectException(Exception\ProfilerCouldNotSnapshotOutsideParentProfile::class); + self::expectException(Exception\ProfilerCouldNotTakeSnapshotOutsideParentProfile::class); - $profiler->snapshot(); + $profiler->takeSnapshot(); } } diff --git a/tests/ProfilingTest.php b/tests/ProfilingTest.php index 445d273..915880c 100644 --- a/tests/ProfilingTest.php +++ b/tests/ProfilingTest.php @@ -17,23 +17,23 @@ public function testProfiles(): void self::assertEquals(1, round($profile->getDuration())); } - public function testAddsSnapshotToProfile(): void + public function testTakesSnapshotOnProfile(): void { $profiling = Profiling::start(); - $profiling->snapshot(); + $profiling->takeSnapshot(); $profile = $profiling->finish(); self::assertCount(2 + 1, $profile->getMemoryUsages()); } - public function testSnapshotThrowsOnFinishedProfile(): void + public function testTakeSnapshotThrowsOnFinishedProfile(): void { $profiling = Profiling::start(); $profiling->finish(); self::expectException(Exception\ProfilingHasBeenAlreadyFinished::class); - $profiling->snapshot(); + $profiling->takeSnapshot(); } public function testFinishThrowsOnFinishedProfile(): void diff --git a/tests/ReadmeTest.php b/tests/ReadmeTest.php index 9a89d96..3dd8951 100644 --- a/tests/ReadmeTest.php +++ b/tests/ReadmeTest.php @@ -23,8 +23,8 @@ public static function getExpectedOutputsOfPhpExamples(): iterable 'basic-profiling' => 'It took 0.0 s to do something.', 'complex-profiling' => '', 'how-to-enable-disable-it' => 'It took 0.0 s to do something.' . 'something' . 'something', - 'snapshot' => 'There are 3 memory usage records.', - 'snapshot-on-tick' => 'There are 3 memory usage records.', + 'take-snapshot' => 'There are 3 memory usage records.', + 'take-snapshot-on-tick' => 'There are 3 memory usage records.', 'cascade-profiling' => 'There are 4 memory usage records.', ]; }