From bdeb4b05dc18810e099ac1b939160c711c89eae5 Mon Sep 17 00:00:00 2001
From: Daniil Gentili <daniil@daniil.it>
Date: Mon, 23 Jan 2023 22:19:50 +0100
Subject: [PATCH] Update docs

---
 README.md                 |  2 --
 examples/GenericLoop.php  | 31 ++++++++++++++++++++
 examples/Loop.php         | 47 +++++++++++++++++++++++++++++++
 examples/PeriodicLoop.php | 31 ++++++++++++++++++++
 lib/GenericLoop.php       | 59 +++++++++++++++++++++++++++++++++++++++
 lib/PeriodicLoop.php      | 44 +++++++++++++++++++++++++++++
 6 files changed, 212 insertions(+), 2 deletions(-)
 create mode 100644 examples/GenericLoop.php
 create mode 100644 examples/Loop.php
 create mode 100644 examples/PeriodicLoop.php
 create mode 100644 lib/GenericLoop.php
 create mode 100644 lib/PeriodicLoop.php

diff --git a/README.md b/README.md
index 001f8e4..089f1fb 100644
--- a/README.md
+++ b/README.md
@@ -184,5 +184,3 @@ class PeriodicLoop extends GenericLoop
 }
 ```
 
-`PeriodicLoop` runs a callback at a periodic interval.  
-The loop can be stopped from the outside by using `stop()` and from the inside by returning `true`.
diff --git a/examples/GenericLoop.php b/examples/GenericLoop.php
new file mode 100644
index 0000000..ace2160
--- /dev/null
+++ b/examples/GenericLoop.php
@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+require 'vendor/autoload.php';
+
+use danog\Loop\GenericLoop;
+
+use function Amp\delay;
+
+/** @var GenericLoop[] */
+$loops = [];
+for ($x = 0; $x < 10; $x++) {
+    $callable = function (GenericLoop $loop): float {
+        static $number = 0;
+        echo "$loop: $number".PHP_EOL;
+        $number++;
+        return $number < 10 ? 1.0 : GenericLoop::STOP;
+    };
+    $loop = new GenericLoop($callable, "Loop number $x");
+    $loop->start();
+    delay(0.1);
+    $loops []= $loop;
+}
+delay(5);
+echo "Resuming prematurely all loops!".PHP_EOL;
+foreach ($loops as $loop) {
+    $loop->resume();
+}
+echo "OK done, waiting 5 more seconds!".PHP_EOL;
+delay(5);
+echo "Closing all loops!".PHP_EOL;
+delay(0.01);
diff --git a/examples/Loop.php b/examples/Loop.php
new file mode 100644
index 0000000..b7add1e
--- /dev/null
+++ b/examples/Loop.php
@@ -0,0 +1,47 @@
+<?php declare(strict_types=1);
+
+require 'vendor/autoload.php';
+
+use danog\Loop\GenericLoop;
+use danog\Loop\Loop;
+
+use function Amp\delay;
+
+class MyLoop extends Loop
+{
+    private int $number = 0;
+
+    public function __construct(private string $name)
+    {
+    }
+
+    protected function loop(): ?float
+    {
+        echo "$this: {$this->number}".PHP_EOL;
+        $this->number++;
+        return $this->number < 10 ? 1.0 : GenericLoop::STOP;
+    }
+
+    public function __toString(): string
+    {
+        return $this->name;
+    }
+}
+
+/** @var MyLoop[] */
+$loops = [];
+for ($x = 0; $x < 10; $x++) {
+    $loop = new MyLoop("Loop number $x");
+    $loop->start();
+    delay(0.1);
+    $loops []= $loop;
+}
+delay(5);
+echo "Resuming prematurely all loops!".PHP_EOL;
+foreach ($loops as $loop) {
+    $loop->resume();
+}
+echo "OK done, waiting 5 more seconds!".PHP_EOL;
+delay(5);
+echo "Closing all loops!".PHP_EOL;
+delay(0.01);
diff --git a/examples/PeriodicLoop.php b/examples/PeriodicLoop.php
new file mode 100644
index 0000000..93fd119
--- /dev/null
+++ b/examples/PeriodicLoop.php
@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+require 'vendor/autoload.php';
+
+use danog\Loop\PeriodicLoop;
+
+use function Amp\delay;
+
+/** @var PeriodicLoop[] */
+$loops = [];
+for ($x = 0; $x < 10; $x++) {
+    $callable = function (PeriodicLoop $loop): bool {
+        static $number = 0;
+        echo "$loop: $number".PHP_EOL;
+        $number++;
+        return $number == 10;
+    };
+    $loop = new PeriodicLoop($callable, "Loop number $x", 1.0);
+    $loop->start();
+    delay(0.1);
+    $loops []= $loop;
+}
+delay(5);
+echo "Resuming prematurely all loops!".PHP_EOL;
+foreach ($loops as $loop) {
+    $loop->resume();
+}
+echo "OK done, waiting 5 more seconds!".PHP_EOL;
+delay(5);
+echo "Closing all loops!".PHP_EOL;
+delay(0.01);
diff --git a/lib/GenericLoop.php b/lib/GenericLoop.php
new file mode 100644
index 0000000..7558893
--- /dev/null
+++ b/lib/GenericLoop.php
@@ -0,0 +1,59 @@
+<?php declare(strict_types=1);
+
+/**
+ * Generic loop.
+ *
+ * @author    Daniil Gentili <daniil@daniil.it>
+ * @copyright 2016-2020 Daniil Gentili <daniil@daniil.it>
+ * @license   https://opensource.org/licenses/MIT MIT
+ */
+
+namespace danog\Loop;
+
+/**
+ * Generic loop, runs single callable.
+ *
+ * @author Daniil Gentili <daniil@daniil.it>
+ */
+class GenericLoop extends Loop
+{
+    /**
+     * Callable.
+     *
+     * @var callable(static):?float
+     */
+    private $callable;
+    /**
+     * Constructor.
+     *
+     * The return value of the callable can be:
+     * * A number - the loop will be paused for the specified number of seconds
+     * * GenericLoop::STOP - The loop will stop
+     * * GenericLoop::PAUSE - The loop will pause forever (or until loop is `resumed()`
+     *                        from outside the loop)
+     * * GenericLoop::CONTINUE - Return this if you want to rerun the loop immediately
+     *
+     * If the callable does not return anything,
+     * the loop will behave is if GenericLoop::PAUSE was returned.
+     *
+     * The callable will be passed the instance of the current loop.
+     *
+     * The loop can be stopped from the outside by using stop().
+     *
+     * @param callable(static):?float $callable Callable to run
+     * @param string   $name     Loop name
+     */
+    public function __construct(callable $callable, private string $name)
+    {
+        $this->callable = $callable;
+    }
+
+    protected function loop(): ?float
+    {
+        return ($this->callable)($this);
+    }
+    public function __toString(): string
+    {
+        return $this->name;
+    }
+}
diff --git a/lib/PeriodicLoop.php b/lib/PeriodicLoop.php
new file mode 100644
index 0000000..da2c0b6
--- /dev/null
+++ b/lib/PeriodicLoop.php
@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+/**
+ * Periodic loop.
+ *
+ * @author    Daniil Gentili <daniil@daniil.it>
+ * @copyright 2016-2020 Daniil Gentili <daniil@daniil.it>
+ * @license   https://opensource.org/licenses/MIT MIT
+ */
+
+namespace danog\Loop;
+
+/**
+ * Periodic loop.
+ *
+ * @author Daniil Gentili <daniil@daniil.it>
+ */
+class PeriodicLoop extends GenericLoop
+{
+    /**
+     * Constructor.
+     *
+     * Runs a callback at a periodic interval.
+     *
+     * The callable will be passed the instance of the current loop.
+     *
+     * The loop can be stopped from the outside by calling stop()
+     * and from the inside by returning `true`.
+     *
+     * @param callable(static):bool $callback Callable to run
+     * @param string   $name     Loop name
+     * @param ?float   $interval Loop interval; if null, pauses indefinitely or until `resume()` is called.
+     */
+    public function __construct(callable $callback, string $name, ?float $interval)
+    {
+        /** @psalm-suppress ArgumentTypeCoercion */
+        parent::__construct(static function (self $loop) use ($callback, $interval): ?float {
+            /** @psalm-suppress ArgumentTypeCoercion */
+            if ($callback($loop) === true) {
+                return GenericLoop::STOP;
+            }
+            return $interval;
+        }, $name);
+    }
+}