Add PcntlTimeout utility class

PcntlTimeout::timeBoxed() can be used to put timeouts on system calls
like flock(). This class works only in UNIX with enabled pcntl
extension. It should not be used in applications which install SIGALRM
signal handler or schedule alarms.

See also: #6

Author: malkusch

classes/util/PcntlTimeout.php

@@ -0,0 +1,91 @@
+<?php
+
+namespace malkusch\lock\util;
+
+use malkusch\lock\exception\TimeoutException;
+use malkusch\lock\exception\LockAcquireException;
+
+/**
+ * Timeout based on a scheduled alarm.
+ *
+ * This class requires the pcntl module.
+ *
+ * @author Markus Malkusch <[email protected]>
+ * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
+ * @license WTFPL
+ * @internal
+ */
+final class PcntlTimeout
+{
+
+    /**
+     * @var int Timeout in seconds
+     */
+    private $timeout;
+
+    /**
+     * Builds the timeout.
+     *
+     * @param int $timeout Timeout in seconds
+     */
+    public function __construct($timeout)
+    {
+        if (!self::isSupported()) {
+            throw new \RuntimeException("PCNTL module not enabled");
+        }
+        if ($timeout <= 0) {
+            throw new \InvalidArgumentException("Timeout must be positiv and non zero");
+        }
+        $this->timeout = $timeout;
+    }
+
+    /**
+     * Runs the code and would eventually time out.
+     *
+     * This method has the side effect, that any signal handler
+     * for SIGALRM will be reset to the default hanlder (SIG_DFL).
+     * It also expects that there is no previously scheduled alarm.
+     * If your application uses alarms ({@link pcntl_alarm()}) or
+     * a signal handler for SIGALRM, don't use this method. It will
+     * interfer with your application and lead to unexpected behaviour.
+     *
+     * @param callable $code Executed code block
+     * @return mixed Return value of the executed block
+     *
+     * @throws TimeoutException Running the code timed out
+     * @throws LockAcquireException Installing the timeout failed
+     */
+    public function timeBoxed($code)
+    {
+        $signal = pcntl_signal(SIGALRM, function () {
+            throw new TimeoutException("Timed out");
+        });
+        if (!$signal) {
+            throw new LockAcquireException("Could not install signal");
+        }
+        $oldAlarm = pcntl_alarm($this->timeout);
+        if ($oldAlarm != 0) {
+            throw new LockAcquireException("Existing alarm was not expected");
+        }
+        try {
+            return call_user_func($code);
+        } finally {
+            pcntl_alarm(0);
+            pcntl_signal_dispatch();
+            pcntl_signal(SIGALRM, SIG_DFL);
+        }
+    }
+
+    /**
+     * Returns if this class is supported by the PHP runtime.
+     *
+     * This class requires the pcntl module. This method checks if
+     * it is available.
+     *
+     * @return bool TRUE if this class is supported by the PHP runtime.
+     */
+    public static function isSupported()
+    {
+        return extension_loaded("pcntl");
+    }
+}

tests/util/PcntlTimeoutTest.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace malkusch\lock\util;
+
+/**
+ * Tests for PcntlTimeout
+ *
+ * @author Markus Malkusch <[email protected]>
+ * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
+ * @license WTFPL
+ * @see PcntlTimeout
+ * @requires pcntl
+ */
+class PcntlTimeoutTest extends \PHPUnit_Framework_TestCase
+{
+
+    /**
+     * A long running system call should be interrupted
+     *
+     * @test
+     * @expectedException malkusch\lock\exception\TimeoutException
+     */
+    public function shouldTimeout()
+    {
+        $timeout = new PcntlTimeout(1);
+
+        $timeout->timeBoxed(function () {
+            sleep(2);
+        });
+    }
+
+    /**
+     * A short running system call should complete its execution
+     *
+     * @test
+     */
+    public function shouldNotTimeout()
+    {
+        $timeout = new PcntlTimeout(1);
+
+        $result = $timeout->timeBoxed(function () {
+            return 42;
+        });
+
+        $this->assertEquals(42, $result);
+    }
+
+    /**
+     * When a previous scheduled alarm exists, it should fail
+     *
+     * @test
+     * @expectedException malkusch\lock\exception\LockAcquireException
+     */
+    public function shouldFailOnExistingAlarm()
+    {
+        try {
+            pcntl_alarm(1);
+            $timeout = new PcntlTimeout(1);
+
+            $timeout->timeBoxed(function () {
+                sleep(1);
+            });
+        } finally {
+            pcntl_alarm(0);
+        }
+    }
+
+    /**
+     * After not timing out, there should be no alarm scheduled
+     *
+     * @test
+     */
+    public function shouldResetAlarmWhenNotTimeout()
+    {
+        $timeout = new PcntlTimeout(3);
+
+        $timeout->timeBoxed(function () {
+        });
+
+        $this->assertEquals(0, pcntl_alarm(0));
+    }
+}