pmmp / snooze

Event loop for handling notifications from multiple threads at once

Snooze

Event-driven thread notification management library for code using the pthreads extension

Use cases

ext-pthreads currently doesn't make it conveniently possible to wait() for notifications from multiple threads simultaneously. This library allows you to do that using a SleeperHandler.

Every thread must receive its own SleeperNotifier (since they are thread-safe, you can share notifiers between threads, but it's recommended not to). The thread should call wakeupSleeper() on its SleeperNotifier, which will cause the thread waiting on SleeperHandler to wake up and process whatever notification was delivered.

It's similar to using the select() system call on an array of sockets or file descriptors, but with threads instead.

Example

class NotifyingThread extends \pmmp\thread\Thread{
	public function __construct(
	    private \pocketmine\snooze\SleeperHandlerEntry $sleeperEntry,
	    private \pmmp\thread\ThreadSafeArray $buffer
	){}

	public function run() : void{
		$stdin = fopen('php://stdin', 'r');
		$notifer = $this->sleeperEntry->createNotifier();
		while(true){
			echo "Type something and press ENTER:\n";
			//do whatever you're doing
			$line = fgets($stdin); //blocks until the user enters something

			//add the line to the buffer
			$this->buffer[] = $line;

			//send a notification to the main thread to tell it that we read a line
			//the parent thread doesn't have to be sleeping to receive this, it'll process it next time it tries to go
			//back to sleep
			//if the parent thread is sleeping, it'll be woken up to process notifications immediately.
			$notifer->wakeupSleeper();
		}
	}
}

$sleeper = new \pocketmine\snooze\SleeperHandler();

$buffer = new \pmmp\thread\ThreadSafeArray();
$sleeperEntry = $sleeper->addNotifier(function() use($buffer) : void{
	//do some things when this notifier sends a notification
	echo "Main thread got line: " . $buffer->shift();
});

$thread = new NotifyingThread($sleeperEntry, $buffer);
$thread->start();

while(true){
	$start = microtime(true);
	//do some work that you do every tick

	//process any pending notifications, then try to sleep 50ms until the next tick
	//this may wakeup at any time to process received notifications
	//if it wakes up and there is still time left to sleep before the specified time, it will go back to sleep again
	//until that time, guaranteeing a delay of at least this amount
	//if there are notifications waiting when this is called, they'll be processed before going to sleep
	$sleeper->sleepUntil($start + 0.05);
}

while(true){
	//alternatively, if you want to only wait for notifications and not tick:
	//but from the pthreads rulebook, only ever wait FOR something!
	//this will wait indefinitely until something wakes it up, and then return immediately
	$sleeper->sleepUntilNotification();
}

$thread->join();
//Unregister the notifier when you're done with it
$sleeper->removeNotifier($sleeperEntry->getNotifierId());

snooze's Issues

Notification counts sometimes become negative

<?php

require_once 'vendor/autoload.php';

class TestThread extends \Thread{
	/**
	 * @var \pocketmine\snooze\SleeperNotifier
	 */
	private $notif;
	/** @var int */
	private $sleepTime;

	public $shutdown = false;

	public function __construct(\pocketmine\snooze\SleeperNotifier $notif, int $sleepTime){
		$this->notif = $notif;
		$this->sleepTime = $sleepTime;
	}

	public function run(){
		while(!$this->shutdown){
			if($this->sleepTime > 0){
				usleep($this->sleepTime);
			}
			$this->notif->wakeupSleeper();
		}
	}
}

assert_options(ASSERT_EXCEPTION, true);

$sleeper = new \pocketmine\snooze\SleeperHandler();

$notif1 = new \pocketmine\snooze\SleeperNotifier();
$sleeper->addNotifier($notif1, function(){});
$thread1 = new TestThread($notif1, 10000);

$notif2 = new \pocketmine\snooze\SleeperNotifier();
$sleeper->addNotifier($notif2, function(){});
$thread2 = new TestThread($notif2, 0);

$thread1->start();
$thread2->start();

try{
	while(true){
		$sleeper->sleepUntil(microtime(true) + 0.05);
	}
}catch(\Throwable $e){
	$thread1->shutdown = true;
	$thread1->join();

	$thread2->shutdown = true;
	$thread2->join();
	throw $e;
}

This code should run forever, but crashes almost immediately:

Fatal error: Uncaught AssertionError: notification count should be >= 0, got -1 in src\ThreadedSleeper.php:66
Stack trace:
#0 src\ThreadedSleeper.php(66): assert(false, 'notification co...')
#1 src\SleeperHandler.php(117): pocketmine\snooze\ThreadedSleeper->clearNotifications(2)
#2 src\SleeperHandler.php(82): pocketmine\snooze\SleeperHandler->processNotifications()
#3 test.php(47): pocketmine\snooze\SleeperHandler->sleepUntil(1526818008.4194)
#4 {main}
  thrown in src\ThreadedSleeper.php on line 66

Switch to using high resolution timers

Recently it was discovered that system time changes during SleeperHandler->sleepUntil() will cause the sleeper to break. Changing the time forward causes the sleeper not to sleep at all for that call (which is OK), but changing the time backwards causes an extended sleep until the originally specified time, which has now moved into the future.

Example:

• caller sleeps for now + 50,000 microseconds
• system time changes back by 3 hours
• sleeper handler now sleeps for 3 hours + 50,000 microseconds

This is undesirable for PocketMine-MP for obvious reasons.

Solutions:

• use the HRTime extension (poorly documented, no git source code)
• force an upgrade to PHP 7.3 to get access to the new hrtime() function

Allow SleeperNotifiers to be non-Threaded

SleeperNotifier being Threaded is costing us performance, because it's necessary to obtain a lock for every read of the properties of SleeperNotifier. This results in 2 additional locks during wakeupSleeper(), which, while they won't be competetive (because nothing else will be attempting to lock), is still entirely useless and a waste of CPU cycles.

Right now, the only use case for a Threaded SleeperNotifier is to allow registering the notifier callback after the thread which uses the notifier has already started; however, I consider this to be poor design, since it could result in some notifications getting lost before the callback is installed, not to mention the fact that the using thread will crash if it attempts to use an unregistered notifier.