feat: add futureTick() function

Author: ace411

README.md

@@ -60,6 +60,7 @@ class Mrloop
   public static parseHttpResponse(string $response, int $headerlimit = 100): iterable
   public addTimer(float $interval, callable $callback): void
   public addPeriodicTimer(float $interval, callable $callback): void
+  public futureTick(callable $callback): void
   public addSignal(int $signal, callable $callback): void
   public run(): void
   public stop(): void
@@ -75,6 +76,7 @@ class Mrloop
 - [`Mrloop::parseHttpResponse`](#mrloopparsehttpresponse)
 - [`Mrloop::addTimer`](#mrloopaddtimer)
 - [`Mrloop::addPeriodicTimer`](#mrloopaddperiodictimer)
+- [`Mrloop::futureTick`](#mrloopfuturetick)
 - [`Mrloop::addSignal`](#mrloopaddsignal)
 - [`Mrloop::run`](#mrlooprun)
 - [`Mrloop::stop`](#mrloopstop)
@@ -641,6 +643,50 @@ Tick: 4
 Tick: 5
 ```
 
+### `Mrloop::futureTick`
+
+```php
+public Mrloop::futureTick(callable $callback): void
+```
+
+Schedules the execution of a specified action for the next event loop tick.
+
+**Parameter(s)**
+
+- **callback** (callable) - The function in which the action to be scheduled is defined.
+
+**Return value(s)**
+
+The function does not return anything.
+
+```php
+use ringphp\Mrloop;
+
+$loop = Mrloop::init();
+$tick = 0;
+
+$loop->futureTick(
+  function () use (&$tick) {
+    echo \sprintf("Tick: %d\n", ++$tick);
+  },
+);
+
+$loop->futureTick(
+  function () use (&$tick) {
+    echo \sprintf("Tick: %d\n", ++$tick);
+  },
+);
+
+$loop->run();
+```
+
+The example above will produce output similar to that in the snippet to follow.
+
+```
+Tick: 1
+Tick: 2
+```
+
 ### `Mrloop::addSignal`
 
 ```php

mrloop_arginfo.h

@@ -55,6 +55,10 @@ ZEND_ARG_TYPE_INFO(0, fd, IS_LONG, 0)
 ZEND_ARG_TYPE_INFO(0, contents, IS_STRING, 0)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Mrloop_futureTick, 0, 0, 1)
+ZEND_ARG_TYPE_INFO(0, callback, IS_CALLABLE, 0)
+ZEND_END_ARG_INFO()
+
 ZEND_METHOD(Mrloop, init);
 ZEND_METHOD(Mrloop, stop);
 ZEND_METHOD(Mrloop, run);
@@ -67,6 +71,7 @@ ZEND_METHOD(Mrloop, addReadStream);
 ZEND_METHOD(Mrloop, addWriteStream);
 ZEND_METHOD(Mrloop, parseHttpResponse);
 ZEND_METHOD(Mrloop, writev);
+ZEND_METHOD(Mrloop, futureTick);
 
 static const zend_function_entry class_Mrloop_methods[] = {
   PHP_ME(Mrloop, init, arginfo_class_Mrloop_init, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC)
@@ -81,4 +86,5 @@ static const zend_function_entry class_Mrloop_methods[] = {
                     PHP_ME(Mrloop, addWriteStream, arginfo_class_Mrloop_addWriteStream, ZEND_ACC_PUBLIC)
                       PHP_ME(Mrloop, parseHttpResponse, arginfo_class_Mrloop_parseHttpResponse, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC)
                         PHP_ME(Mrloop, writev, arginfo_class_Mrloop_writev, ZEND_ACC_PUBLIC)
-                          PHP_FE_END};
+                          PHP_ME(Mrloop, futureTick, arginfo_class_Mrloop_futureTick, ZEND_ACC_PUBLIC)
+                            PHP_FE_END};

php_mrloop.c

@@ -91,6 +91,13 @@ PHP_METHOD(Mrloop, writev)
 }
 /* }}} */
 
+/* {{{ proto void Mrloop::futureTick( callable callback ) */
+PHP_METHOD(Mrloop, futureTick)
+{
+  php_mrloop_add_future_tick(INTERNAL_FUNCTION_PARAM_PASSTHRU);
+}
+/* }}} */
+
 /* {{{ PHP_MINIT_FUNCTION */
 PHP_MINIT_FUNCTION(mrloop)
 {

src/loop.c

@@ -102,7 +102,7 @@ static int php_mrloop_timer_cb(void *data)
   zval_ptr_dtor(&result);
   efree(cb);
 
-  return type == PHP_MRLOOP_TIMER ? 0 : 1;
+  return type == PHP_MRLOOP_TIMER || type == PHP_MRLOOP_FUTURE_TICK ? 0 : 1;
 }
 static void php_mrloop_add_timer(INTERNAL_FUNCTION_PARAMETERS)
 {
@@ -162,6 +162,33 @@ static void php_mrloop_add_periodic_timer(INTERNAL_FUNCTION_PARAMETERS)
 
   return;
 }
+static void php_mrloop_add_future_tick(INTERNAL_FUNCTION_PARAMETERS)
+{
+  zval *obj;
+  php_mrloop_cb_t *cb;
+  php_mrloop_t *this;
+  zend_fcall_info fci;
+  zend_fcall_info_cache fci_cache;
+
+  fci = empty_fcall_info;
+  fci_cache = empty_fcall_info_cache;
+  obj = getThis();
+
+  ZEND_PARSE_PARAMETERS_START(1, 1)
+  Z_PARAM_FUNC(fci, fci_cache)
+  ZEND_PARSE_PARAMETERS_END();
+
+  this = PHP_MRLOOP_OBJ(obj);
+  cb = emalloc(sizeof(php_mrloop_cb_t));
+  PHP_CB_TO_MRLOOP_CB(cb, fci, fci_cache);
+
+  cb->signal = PHP_MRLOOP_FUTURE_TICK;
+  cb->data = this->loop;
+
+  mr_call_soon(this->loop, php_mrloop_timer_cb, cb);
+
+  return;
+}
 
 static void php_mrloop_readv_cb(void *data, int res)
 {

src/loop.h

@@ -28,6 +28,7 @@
 #define DEFAULT_HTTP_HEADER_LIMIT 100
 #define PHP_MRLOOP_TIMER 1
 #define PHP_MRLOOP_PERIODIC_TIMER 2
+#define PHP_MRLOOP_FUTURE_TICK 3
 
 struct php_mrloop_t;
 struct php_mrloop_cb_t;
@@ -130,6 +131,8 @@ static int php_mrloop_timer_cb(void *data);
 static void php_mrloop_add_timer(INTERNAL_FUNCTION_PARAMETERS);
 /* executes a specified action in perpetuity with each successive execution occurring after a specified time interval */
 static void php_mrloop_add_periodic_timer(INTERNAL_FUNCTION_PARAMETERS);
+/* schedules the execution of a specified action for the next event loop tick */
+static void php_mrloop_add_future_tick(INTERNAL_FUNCTION_PARAMETERS);
 
 /* mrloop-bound callback specified during invocation of vectorized read function */
 static void php_mrloop_readv_cb(void *data, int res);

tests/013.phpt

@@ -0,0 +1,30 @@
+--TEST--
+futureTick() schedules the execution of a specified action for the next event loop tick
+--FILE--
+<?php
+
+use ringphp\Mrloop;
+
+$loop = Mrloop::init();
+
+$tick = 0;
+
+$loop->futureTick(
+  function () use (&$tick) {
+    echo \sprintf("Tick: %d\n", ++$tick);
+  },
+);
+
+$loop->futureTick(
+  function () use ($loop, &$tick) {
+    echo \sprintf("Tick: %d\n", ++$tick);
+    $loop->stop();
+  },
+);
+
+$loop->run();
+
+?>
+--EXPECT--
+Tick: 1
+Tick: 2