Merge pull request #383 from openswoole/feat/fiber_api

Feat/fiber api

Author: doubaokun

.github/workflows/ext.yml

@@ -48,11 +48,11 @@ jobs:
     - name: Install dependencies
       run: |
         brew install autoconf
-        brew install shivammathur/php/php@8.2
-        brew link --overwrite --force shivammathur/php/php@8.2
+        brew install shivammathur/php/php@8.3
+        brew link --overwrite --force shivammathur/php/php@8.3
         brew install pcre2
         brew install c-ares
-        ln -s /opt/homebrew/include/pcre2.h /opt/homebrew/opt/php@8.2/include/php/ext/pcre/pcre2.h
+        ln -s /opt/homebrew/include/pcre2.h /opt/homebrew/opt/php@8.3/include/php/ext/pcre/pcre2.h
     - uses: actions/checkout@v4
     - name: phpize
       run: phpize
@@ -70,11 +70,9 @@ jobs:
     if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
     strategy:
       matrix:
-        php-version: [ '8.2.26']
+        php-version: [ '8.3.15']
         alpine-version: [ '3.20' ]
         include:
-          - php-version: '8.3.15'
-            alpine-version: '3.20'
           - php-version: '8.4.2'
             alpine-version: '3.21'
           - php-version: '8.5.0'

.github/workflows/test-laravel.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        php: [8.2, 8.3, 8.4, 8.5]
+        php: [8.3, 8.4, 8.5]
     steps:
     - uses: actions/checkout@v4
     - name: Setup PHP

.github/workflows/test-linux.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: ['8.2', '8.3', '8.4', '8.5']
+        php: ['8.3', '8.4', '8.5']
     steps:
     - uses: actions/checkout@v4
     - name: Show machine information

ci/docker-compile.sh

@@ -15,6 +15,7 @@ echo "/tmp/core.%e.%p" > /proc/sys/kernel/core_pattern 2>/dev/null || true
 #-----------compile------------
 #-------print error only-------
 export TERM=${TERM:-dumb}
+
 cd "${__DIR__}" && cd ../ && \
 ./clear.sh > /dev/null && \
 phpize --clean > /dev/null && \
@@ -35,3 +36,10 @@ docker-php-ext-enable --ini-name zzz-docker-php-ext-openswoole.ini openswoole >
 echo "zend.max_allowed_stack_size=-1" > /usr/local/etc/php/conf.d/zzz-stack-size.ini && \
 php --ri curl && \
 php --ri openswoole
+
+#-----------install xdebug for fiber context tests (disabled by default)------------
+echo "" && echo "📦 Installing xdebug..." && echo ""
+pecl install xdebug > /dev/null 2>&1 && \
+docker-php-ext-enable xdebug > /dev/null 2>&1 && \
+echo "xdebug.mode=off" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
+echo "xdebug installed (mode=off)" || echo "⚠️ xdebug installation failed, fiber xdebug tests will be skipped"

ci/docker-route.sh

@@ -5,6 +5,9 @@ __DIR__=$(cd "$(dirname "$0")";pwd)
 # enter the dir
 cd "${__DIR__}"
 
+# map SWOOLE_BRANCH (from docker-compose) to CI_BRANCH (used by run-tests.sh)
+[ -n "${SWOOLE_BRANCH}" ] && export CI_BRANCH="${SWOOLE_BRANCH}"
+
 # show system info
 date && echo ""
 uname -a && echo ""

ci/route.sh

@@ -4,7 +4,7 @@ __DIR__=$(cd "$(dirname "$0")";pwd)
 
 export DOCKER_COMPOSE_VERSION="5.0.2"
 
-export PHP_VERSION=${PHP_VERSION:-${1:-"8.2"}}
+export PHP_VERSION=${PHP_VERSION:-${1:-"8.3"}}
 export CI_BRANCH=${CI_BRANCH:-${2:-"master"}}
 
 [ -z "${CI_BRANCH}" ] && export CI_BRANCH="master"
@@ -31,6 +31,19 @@ check_docker_dependency(){
     fi
 }
 
+wait_for_mysql(){
+    echo "⏳ Waiting for MySQL to be ready..."
+    for i in $(seq 1 30); do
+        if docker exec mysql mysqladmin ping -h 127.0.0.1 -u root -proot --silent > /dev/null 2>&1; then
+            echo "✅ MySQL is ready"
+            return 0
+        fi
+        sleep 2
+    done
+    echo "❌ MySQL failed to start within 60 seconds!"
+    return 1
+}
+
 start_docker_containers(){
     remove_docker_containers
     cd ${__DIR__} && \
@@ -40,12 +53,12 @@ start_docker_containers(){
         echo "\n❌ Create containers failed!"
         exit 1
     fi
+    wait_for_mysql
 }
 
 remove_docker_containers(){
     cd ${__DIR__} && \
-    docker compose kill > /dev/null 2>&1 && \
-    docker compose rm -f > /dev/null 2>&1
+    docker compose down --remove-orphans -v > /dev/null 2>&1
 }
 
 run_tests_in_docker(){

config.m4

@@ -641,6 +641,7 @@ if test "$PHP_SWOOLE" != "no"; then
         src/coroutine/base.cc \
         src/coroutine/channel.cc \
         src/coroutine/context.cc \
+        src/coroutine/fiber_context.cc \
         src/coroutine/file_lock.cc \
         src/coroutine/hook.cc \
         src/coroutine/selector.cc \

ext-src/php_swoole.cc

@@ -140,6 +140,10 @@ STD_ZEND_INI_BOOLEAN("openswoole.enable_coroutine", "On", PHP_INI_ALL, OnUpdateB
  * enable swoole coroutine epreemptive scheduler
  */
 STD_ZEND_INI_BOOLEAN("openswoole.enable_preemptive_scheduler", "Off", PHP_INI_ALL, OnUpdateBool, enable_preemptive_scheduler, zend_openswoole_globals, openswoole_globals)
+/**
+ * use PHP fiber context for coroutines (enables xdebug tracing)
+ */
+STD_ZEND_INI_BOOLEAN("openswoole.use_fiber_context", "Off", PHP_INI_ALL, OnUpdateBool, use_fiber_context, zend_openswoole_globals, openswoole_globals)
 /**
  * display error
  */
@@ -154,6 +158,7 @@ PHP_INI_END()
 static void php_swoole_init_globals(zend_openswoole_globals *openswoole_globals) {
     openswoole_globals->enable_coroutine = 1;
     openswoole_globals->enable_preemptive_scheduler = 0;
+    openswoole_globals->use_fiber_context = 0;
     openswoole_globals->socket_buffer_size = SW_SOCKET_BUFFER_SIZE;
     openswoole_globals->display_errors = 1;
 }
@@ -1226,10 +1231,19 @@ PHP_MINFO_FUNCTION(openswoole) {
     php_info_print_table_row(2, "Built", buf);
 #if defined(SW_USE_THREAD_CONTEXT)
     php_info_print_table_row(2, "coroutine", "enabled with thread context");
-#elif defined(SW_USE_ASM_CONTEXT)
-    php_info_print_table_row(2, "coroutine", "enabled with boost asm context");
 #else
-    php_info_print_table_row(2, "coroutine", "enabled with ucontext");
+    if (swoole::Coroutine::use_fiber_context) {
+        php_info_print_table_row(2, "coroutine", "enabled with fiber context");
+    }
+#if defined(SW_USE_ASM_CONTEXT)
+    else {
+        php_info_print_table_row(2, "coroutine", "enabled with boost asm context");
+    }
+#else
+    else {
+        php_info_print_table_row(2, "coroutine", "enabled with ucontext");
+    }
+#endif
 #endif
 #ifdef SW_DEBUG
     php_info_print_table_row(2, "debug", "enabled");

ext-src/php_swoole_private.h

@@ -376,11 +376,7 @@ zend_bool php_swoole_signal_isset_handler(int signo);
 #endif
 /*}}}*/
 
-/* PHP 8 compatibility macro {{{*/
-#define sw_zend7_object zend_object
-#define SW_Z7_OBJ_P(object) object
 #define SW_Z8_OBJ_P(zobj) Z_OBJ_P(zobj)
-/*}}}*/
 
 typedef ssize_t php_stream_size_t;
 

ext-src/swoole_coroutine.cc

@@ -62,7 +62,7 @@ bool PHPCoroutine::interrupt_thread_running = false;
 
 // extern void php_swoole_load_library();
 
-#if PHP_VERSION_ID >= 80500
+#if PHP_VERSION_ID >= 80400
 static zif_handler ori_exit_handler = nullptr;
 #else
 static user_opcode_handler_t ori_exit_handler = nullptr;
@@ -203,12 +203,7 @@ static int coro_exit_handler(zend_execute_data *execute_data) {
 
         if (opline->op1_type != IS_UNUSED) {
             if (opline->op1_type == IS_CONST) {
-                // see: https://github.com/php/php-src/commit/e70618aff6f447a298605d07648f2ce9e5a284f5
-#ifdef EX_CONSTANT
-                exit_status = EX_CONSTANT(opline->op1);
-#else
                 exit_status = RT_CONSTANT(opline, opline->op1);
-#endif
             } else {
                 exit_status = EX_VAR(opline->op1.var);
             }
@@ -231,8 +226,8 @@ static int coro_exit_handler(zend_execute_data *execute_data) {
     return ZEND_USER_OPCODE_DISPATCH;
 }
 #endif
-#if PHP_VERSION_ID >= 80500
-/* PHP 8.5+: exit() is a regular function, intercept via function handler replacement */
+#if PHP_VERSION_ID >= 80400
+/* PHP 8.4+: exit() is a regular function, intercept via function handler replacement */
 PHP_FUNCTION(swoole_exit) {
     zend_long flags = 0;
     if (Coroutine::get_current()) {
@@ -313,10 +308,9 @@ void PHPCoroutine::activate() {
         return;
     }
 
-    if (zend_hash_str_find_ptr(&module_registry, ZEND_STRL("xdebug"))) {
-        php_swoole_fatal_error(
-            E_WARNING,
-            "Using Xdebug in coroutines is extremely dangerous, please notice that it may lead to coredump!");
+    /* Apply INI setting for fiber context if not already set via Co::set() */
+    if (SWOOLE_G(use_fiber_context)) {
+        Coroutine::set_use_fiber_context(true);
     }
 
     /* init reactor and register event wait */
@@ -488,32 +482,40 @@ inline void PHPCoroutine::save_vm_stack(PHPContext *task) {
     task->error_handling = EG(error_handling);
     task->exception_class = EG(exception_class);
     task->exception = EG(exception);
-    if (UNEXPECTED(task->in_silence)) {
-        task->tmp_error_reporting = EG(error_reporting);
-        EG(error_reporting) = task->ori_error_reporting;
+    if (!Coroutine::use_fiber_context) {
+        // With fiber context, zend_fiber_switch_context manages EG(error_reporting).
+        // Do not modify it here to avoid conflicts.
+        if (UNEXPECTED(task->in_silence)) {
+            task->tmp_error_reporting = EG(error_reporting);
+            EG(error_reporting) = task->ori_error_reporting;
+        }
     }
 }
 
 inline void PHPCoroutine::restore_vm_stack(PHPContext *task) {
+    if (!Coroutine::use_fiber_context) {
+        // With fiber context, zend_fiber_switch_context() saves/restores these fields
+        // automatically. Restoring them here would conflict and corrupt VM state.
 #ifdef SW_CORO_SWAP_BAILOUT
-    EG(bailout) = task->bailout;
+        EG(bailout) = task->bailout;
 #endif
-    EG(vm_stack_top) = task->vm_stack_top;
-    EG(vm_stack_end) = task->vm_stack_end;
-    EG(vm_stack) = task->vm_stack;
-    EG(vm_stack_page_size) = task->vm_stack_page_size;
-    EG(current_execute_data) = task->execute_data;
-    EG(jit_trace_num) = task->jit_trace_num;
+        EG(vm_stack_top) = task->vm_stack_top;
+        EG(vm_stack_end) = task->vm_stack_end;
+        EG(vm_stack) = task->vm_stack;
+        EG(vm_stack_page_size) = task->vm_stack_page_size;
+        EG(current_execute_data) = task->execute_data;
+        EG(jit_trace_num) = task->jit_trace_num;
 #ifdef ZEND_CHECK_STACK_LIMIT
-    EG(stack_base) = task->stack_base;
-    EG(stack_limit) = task->stack_limit;
+        EG(stack_base) = task->stack_base;
+        EG(stack_limit) = task->stack_limit;
 #endif
+        if (UNEXPECTED(task->in_silence)) {
+            EG(error_reporting) = task->tmp_error_reporting;
+        }
+    }
     EG(error_handling) = task->error_handling;
     EG(exception_class) = task->exception_class;
     EG(exception) = task->exception;
-    if (UNEXPECTED(task->in_silence)) {
-        EG(error_reporting) = task->tmp_error_reporting;
-    }
 }
 
 inline void PHPCoroutine::save_og(PHPContext *task) {
@@ -608,7 +610,18 @@ void PHPCoroutine::on_close(void *arg) {
     if (SwooleG.max_concurrency > 0 && task->pcid == -1) {
         SwooleWG.worker_concurrency--;
     }
-    vm_stack_destroy();
+    if (Coroutine::use_fiber_context) {
+        // With fiber context, EG(vm_stack) is the caller's (restored by zend_fiber_switch_context).
+        // Destroy the coroutine's VM stack using the pointer saved in the task struct.
+        zend_vm_stack stack = task->vm_stack;
+        while (stack != nullptr) {
+            zend_vm_stack p = stack->prev;
+            efree(stack);
+            stack = p;
+        }
+    } else {
+        vm_stack_destroy();
+    }
     restore_task(origin_task);
 
     swoole_trace_log(SW_TRACE_COROUTINE,
@@ -696,16 +709,20 @@ void PHPCoroutine::main_func(void *arg) {
         task->enable_scheduler = true;
 
 #ifdef ZEND_CHECK_STACK_LIMIT
-        if(task->co) {
-            EG(stack_base) = (void*)((uintptr_t)task->co->get_context().get_stack() + task->co->get_context().get_stack_size());
-            zend_ulong reserve = EG(reserved_stack_size);
-        #ifdef __APPLE__
-            reserve = reserve * 2;
-        #endif
-            EG(stack_limit) = (int8_t*)task->co->get_context().get_stack() + reserve;
-        } else {
-            EG(stack_base) = nullptr;
-            EG(stack_limit) = nullptr;
+        if (!Coroutine::use_fiber_context) {
+            // Fiber context: zend_fiber_switch_context() sets EG(stack_base/stack_limit) automatically.
+            // Other backends: we must set them manually from the coroutine stack.
+            if(task->co) {
+                EG(stack_base) = (void*)((uintptr_t)task->co->get_context().get_stack() + task->co->get_context().get_stack_size());
+                zend_ulong reserve = EG(reserved_stack_size);
+            #ifdef __APPLE__
+                reserve = reserve * 2;
+            #endif
+                EG(stack_limit) = (int8_t*)task->co->get_context().get_stack() + reserve;
+            } else {
+                EG(stack_base) = nullptr;
+                EG(stack_limit) = nullptr;
+            }
         }
 #endif
         save_vm_stack(task);
@@ -788,6 +805,14 @@ void PHPCoroutine::main_func(void *arg) {
         }
         zval_ptr_dtor(retval);
 
+        if (Coroutine::use_fiber_context) {
+            // Save the coroutine's final VM stack state so on_close can properly
+            // destroy it. After main_func returns, fiber_func returns to the PHP
+            // fiber trampoline which does the final context switch. The coroutine's
+            // EG(vm_stack) is only accessible via this saved pointer in on_close.
+            save_vm_stack(task);
+        }
+
         if (UNEXPECTED(EG(exception))) {
             zend_exception_error(EG(exception), E_ERROR);
             // TODO: php8 don't exit on exceptions, but no reason to continue, fix this in the future
@@ -895,8 +920,8 @@ void php_swoole_coroutine_rinit() {
         ori_exit_handler = zend_get_user_opcode_handler(ZEND_EXIT);
         zend_set_user_opcode_handler(ZEND_EXIT, coro_exit_handler);
 #endif
-#if PHP_VERSION_ID >= 80500
-        /* PHP 8.5+: exit() is a regular function, replace its handler */
+#if PHP_VERSION_ID >= 80400
+        /* PHP 8.4+: exit() is a regular function, replace its handler */
         zend_function *exit_fn = (zend_function *) zend_hash_str_find_ptr(EG(function_table), ZEND_STRL("exit"));
         if (exit_fn) {
             ori_exit_handler = exit_fn->internal_function.handler;
@@ -912,7 +937,7 @@ void php_swoole_coroutine_rinit() {
 }
 
 void php_swoole_coroutine_rshutdown() {
-#if PHP_VERSION_ID >= 80500
+#if PHP_VERSION_ID >= 80400
     /* Restore original exit() handler */
     if (ori_exit_handler) {
         zend_function *exit_fn = (zend_function *) zend_hash_str_find_ptr(EG(function_table), ZEND_STRL("exit"));
@@ -993,6 +1018,7 @@ static PHP_METHOD(swoole_coroutine, stats) {
     add_assoc_long_ex(return_value, ZEND_STRL("coroutine_num"), Coroutine::count());
     add_assoc_long_ex(return_value, ZEND_STRL("coroutine_peak_num"), Coroutine::get_peak_num());
     add_assoc_long_ex(return_value, ZEND_STRL("coroutine_last_cid"), Coroutine::get_last_cid());
+    add_assoc_bool_ex(return_value, ZEND_STRL("use_fiber_context"), Coroutine::use_fiber_context);
 }
 
 static PHP_METHOD(swoole_coroutine, run) {