Move time-warp

README.md

@@ -16,6 +16,8 @@ composer require innmind/time
 
 ## Usage
 
+### Accessing time
+
 ```php
 use Innmind\Time\{
     Clock,
@@ -38,6 +40,34 @@ Here we reference 2 points in time, the first is the exact moment we call `now`
 
 The method `at()` accepts any string that is allowed by `\DateTimeImmutable`.
 
+### Halt process
+
+```php
+use Innmind\Time\{
+    Halt
+    Period,
+};
+
+function yourApp(Halt $halt): void
+{
+    // do something
+    $halt(Period::minute(42))->unwrap();
+    // do some more
+}
+
+yourApp(Halt::new());
+```
+
+This example will halt your program for 42 minutes.
+
+#### Logging
+
+```php
+use Innmind\Time\Halt;
+use Psr\Log\LoggerInterface;
+
+$halt = Halt::logger($halt, /** an instance of LoggerInterface */);
+
 ## Documentation
 
 Full documentation is available at <https://innmind.org/time/>.

proofs/halt.php

@@ -0,0 +1,63 @@
+<?php
+declare(strict_types = 1);
+
+use Innmind\Time\{
+    Halt,
+    Period,
+};
+use Innmind\Immutable\{
+    Attempt,
+    SideEffect,
+};
+use Psr\Log\NullLogger;
+
+return static function() {
+    yield test(
+        'Halt::new()',
+        static fn($assert) => $assert
+            ->time(static function() use ($assert) {
+                $assert
+                    ->object(
+                        Halt::new()(Period::millisecond(500))->unwrap(),
+                    )
+                    ->instance(SideEffect::class);
+            })
+            ->inMoreThan()
+            ->milliseconds(500),
+    );
+
+    yield test(
+        'Prevent converting months',
+        static fn($assert) => $assert->throws(
+            static fn() => Halt::new()(Period::month(1))->unwrap(),
+            LogicException::class,
+        ),
+    );
+
+    yield test(
+        'Halt::logger()',
+        static fn($assert) => $assert
+            ->object(
+                Halt::logger(Halt::new(), new NullLogger)(
+                    Period::millisecond(100),
+                )->unwrap(),
+            )
+            ->instance(SideEffect::class),
+    );
+
+    yield test(
+        'Halt::via()',
+        static function($assert) {
+            $period = Period::millisecond(500);
+            $expected = Attempt::result(SideEffect::identity);
+
+            $halt = Halt::via(static function($in) use ($assert, $period, $expected) {
+                $assert->same($period, $in);
+
+                return $expected;
+            });
+
+            $assert->same($expected, $halt($period));
+        },
+    );
+};

src/Halt.php

@@ -0,0 +1,68 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\Time;
+
+use Innmind\Time\Halt\{
+    Implementation,
+    Usleep,
+    Logger,
+    Async,
+    Via,
+};
+use Innmind\Immutable\{
+    Attempt,
+    SideEffect,
+};
+use Psr\Log\LoggerInterface;
+
+final class Halt
+{
+    private function __construct(
+        private Implementation $implementation,
+    ) {
+    }
+
+    /**
+     * Halt the program for the given period
+     *
+     * @return Attempt<SideEffect>
+     */
+    #[\NoDiscard]
+    public function __invoke(Period $period): Attempt
+    {
+        return ($this->implementation)($period);
+    }
+
+    #[\NoDiscard]
+    public static function new(): self
+    {
+        return new self(Usleep::new());
+    }
+
+    #[\NoDiscard]
+    public static function logger(self $self, LoggerInterface $logger): self
+    {
+        return new self(Logger::psr($self->implementation, $logger));
+    }
+
+    /**
+     * @internal
+     */
+    #[\NoDiscard]
+    public static function async(Clock $clock): self
+    {
+        return new self(Async::of($clock));
+    }
+
+    /**
+     * @internal
+     *
+     * @param callable(Period): Attempt<SideEffect> $via
+     */
+    #[\NoDiscard]
+    public static function via(callable $via): self
+    {
+        return new self(Via::of($via));
+    }
+}

src/Halt/Async.php

@@ -0,0 +1,41 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\Time\Halt;
+
+use Innmind\Time\{
+    Halt\Async\Suspended,
+    Halt\Async\Resumable,
+    Clock,
+    Period,
+};
+use Innmind\Immutable\Attempt;
+
+/**
+ * @internal
+ */
+final class Async implements Implementation
+{
+    private function __construct(
+        private Clock $clock,
+    ) {
+    }
+
+    #[\Override]
+    public function __invoke(Period $period): Attempt
+    {
+        /** @var Resumable */
+        $return = \Fiber::suspend(Suspended::of(
+            $this->clock->now(),
+            $period,
+        ));
+
+        return $return->unwrap();
+    }
+
+    #[\NoDiscard]
+    public static function of(Clock $clock): self
+    {
+        return new self($clock);
+    }
+}

src/Halt/Async/Resumable.php

@@ -0,0 +1,44 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\Time\Halt\Async;
+
+use Innmind\Immutable\{
+    Attempt,
+    SideEffect,
+};
+
+/**
+ * @internal
+ * @psalm-immutable
+ */
+final class Resumable
+{
+    /**
+     * @param Attempt<SideEffect> $result
+     */
+    private function __construct(
+        private Attempt $result,
+    ) {
+    }
+
+    /**
+     * @psalm-pure
+     *
+     * @param Attempt<SideEffect> $result
+     */
+    #[\NoDiscard]
+    public static function of(Attempt $result): self
+    {
+        return new self($result);
+    }
+
+    /**
+     * @return Attempt<SideEffect>
+     */
+    #[\NoDiscard]
+    public function unwrap(): Attempt
+    {
+        return $this->result;
+    }
+}

src/Halt/Async/Suspended.php

@@ -0,0 +1,88 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\Time\Halt\Async;
+
+use Innmind\Time\{
+    Clock,
+    Point,
+    Period,
+};
+use Innmind\Immutable\{
+    Attempt,
+    SideEffect,
+};
+
+/**
+ * @internal
+ */
+final class Suspended
+{
+    /**
+     * @psalm-mutation-free
+     */
+    private function __construct(
+        private Point $at,
+        private Period $period,
+        private Period $remaining,
+    ) {
+    }
+
+    /**
+     * @psalm-pure
+     */
+    #[\NoDiscard]
+    public static function of(
+        Point $at,
+        Period $period,
+    ): self {
+        return new self($at, $period, $period);
+    }
+
+    /**
+     * @param Attempt<SideEffect> $result
+     */
+    #[\NoDiscard]
+    public function next(
+        Clock $clock,
+        Attempt $result,
+    ): self|Resumable {
+        $error = $result->match(
+            static fn() => false,
+            static fn() => true,
+        );
+
+        if ($error) {
+            // The drawback of resuming with the error is that an error occuring
+            // due to another Fiber will affect all of them as for now there is
+            // no way to distinguish due to which Fiber the halt failed.
+            // This will need real world experience to know if this approach is
+            // ok or not.
+            return Resumable::of($result);
+        }
+
+        $now = $clock->now();
+        $expectedEnd = $this->at->goForward($this->period);
+
+        if ($now->aheadOf($expectedEnd)) {
+            return Resumable::of($result);
+        }
+
+        return new self(
+            $this->at,
+            $this->period,
+            $expectedEnd
+                ->elapsedSince($now)
+                ->asPeriod(),
+        );
+    }
+
+    /**
+     * @psalm-mutation-free
+     */
+    #[\NoDiscard]
+    public function period(): Period
+    {
+        return $this->remaining;
+    }
+}

src/Halt/Implementation.php

@@ -0,0 +1,24 @@
+<?php
+declare(strict_types = 1);
+
+namespace Innmind\Time\Halt;
+
+use Innmind\Time\Period;
+use Innmind\Immutable\{
+    Attempt,
+    SideEffect,
+};
+
+/**
+ * @internal
+ */
+interface Implementation
+{
+    /**
+     * Halt the program for the given period
+     *
+     * @return Attempt<SideEffect>
+     */
+    #[\NoDiscard]
+    public function __invoke(Period $period): Attempt;
+}