4.x is outdated, please check the latest version 22.x

Latest version: pecl install openswoole-22.1.2

Coroutine Configuration Options

When running a Swoole HTTP Server or using coroutines within a container context, you can set a range of configuration options to dictate how Swoole should operate with coroutines.

Coroutines have configuration options and these options can be set in a few different ways, depending on how you are using Swoole. If you are running a Swoole HTTP server you should be using Swoole\Coroutine::set() before you start your server to change any default coroutine options.

You can set coroutine options within your $server->set() method but this is not recommended and will end up overwriting any changes set by Swoole\Coroutine::set(). For any server configuration (TCP or HTTP), you should do this from the server classes and for any coroutine configuration, you should only be using Swoole\Coroutine::set().

Also consider that you don't need to run a Swoole server of any kind in order to use coroutines, you can simply use them directly inside a PHP file without a server running, you just need to wrap them inside a coroutine container context, which we are going to explore next...

Configuration Example

Before you use any coroutines you can use Swoole\Coroutine::set(array $options) to change default options:

$options = [
    'max_concurrency' => 0,
    'max_coroutine' => 4096,
    'stack_size' => 2 * 1024 * 1024,
    'socket_connect_timeout' => 1,
    'socket_timeout' => -1,
    'socket_read_timeout' => -1,
    'socket_write_timeout' => -1,
    'log_level' => SWOOLE_LOG_INFO,
    'hook_flags' => SWOOLE_HOOK_ALL,
    'trace_flags' => SWOOLE_TRACE_ALL,
    'dns_cache_expire' => 60,
    'dns_cache_capacity' => 1000,
    'dns_server' => '',
    'display_errors' => false,
    'aio_core_worker_num' => 10,
    'aio_worker_num' => 10,
    'aio_max_wait_time' => 1,
    'aio_max_idle_time' => 1,
    'exit_condition' => function() {
        return Swoole\Coroutine::stats()['coroutine_num'] === 0;



Coroutine Options with a Server

If you are using a Swoole server of any kind and you want to change default coroutine options, you can use Swoole\Coroutine::set() to do this, it is only recommended to be done before you start your server.


// Set coroutine options before you start a server...
        'max_coroutine' => 800,

$server = new Swoole\HTTP\Server("", 9501);

 * If this was not a comment, then the max_coroutine option
 * would be overwritten and is not recommended, use the
 * specific coroutine set method to change coroutine
 * options and use the server set method for server
 * options only.
    //'max_coroutine' => 100,

$server->on("Start", function (Swoole\Http\Server $server)
    echo "Swoole HTTP server  started at\n";

    // Show Server settings
    var_dump('Server Settings: ', $server->setting);

    // Show Coroutine options
    var_dump('Coroutine Options: ', Swoole\Coroutine::getOptions());



You can change coroutine options on the fly, although it is not recommended, it is possible. Some options can only be set once at the beginning. The Swoole hook_flags options can be changed on the fly throughout a process or server lifetime.

Configuration Overview

NameAvailable FromDescription
max_concurrencyv4.7.1The max number of concurrent requests that can be executed at the same time, if this limit is reached the other requests are queued to be executed but not dropped to protect the server.
max_coroutine-The max number of coroutines that can be created, if this limit is reached new coroutines cannot be created and a `503` response error is returned when using the Swoole HTTP Server or an error will be thrown.
stack_size-Set the memory size of the initial stack of a single coroutine, the default is 2M.
log_levelv4.0.0Set the log level debug output
trace_flagsv4.0.0Decide which logs you want to track, reduce the number of logs thrown by only selecting what you want to log.
socket_connect_timeoutv4.2.10Set the TCP connection timeout when establishing a connection, sending or receiving data.
socket_read_timeoutv4.3.0Set the TCP read timeout.
socket_write_timeoutv4.3.0Set the TCP write timeout.
socket_dns_timeoutv4.4.0Set the Domain name resolution timeout.
socket_timeoutv4.2.10Set the send or receive timeout for a socket connection.
dns_cache_expirev4.2.11Set the Swoole DNS cache invalidation timeout, the default is 60 seconds.
dns_cache_capacityv4.2.11Set the Swoole DNS cache capacity, the default is 1000K.
hook_flagsv4.4.0Coroutine-based hook configuration, set which coroutine hooks you want to enable.
enable_preemptive_schedulerv4.4.0Set when to coroutine preemptive scheduling, the maximum execution time of the coroutine is 10ms, which will overwrite the ini configuration.
dns_serverv4.5.0Set the server for dns query, the default is "".
exit_conditionv4.5.0Pass a callable and customize reactor exit conditions by returning true or false.
enable_deadlock_checkv4.6.0Set whether to enable coroutine deadlock detection, enabled by default
deadlock_check_disable_tracev4.6.0Set whether to output stack frames for coroutine deadlock detection
deadlock_check_limitv4.6.0Limit the maximum number of outputs during coroutine deadlock detection
deadlock_check_depthv4.6.0Limit the number of stack frames returned during coroutine deadlock detection
Last updated on August 31, 2022