Latest version: pecl install openswoole-22.1.2 | composer require openswoole/core:22.1.5

Coroutine Configuration Options

When running a OpenSwoole HTTP Server or using coroutines within a container context, you can set a range of configuration options to dictate how OpenSwoole 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 OpenSwoole. If you are running a OpenSwoole HTTP server you should be using OpenSwoole\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 OpenSwoole\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 OpenSwoole\Coroutine::set().

Also consider that you don't need to run a OpenSwoole 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 OpenSwoole\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' => OpenSwoole\Constant::LOG_INFO,
    'hook_flags' => OpenSwoole\Runtime::HOOK_ALL,
    'trace_flags' => OpenSwoole\Constant::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 OpenSwoole\Coroutine::stats()['coroutine_num'] === 0;



Coroutine Options with a Server

If you are using a OpenSwoole server of any kind and you want to change default coroutine options, you can use OpenSwoole\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 OpenSwoole\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 (OpenSwoole\Http\Server $server)
    echo "OpenSwoole HTTP server  started at\n";

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

    // Show Coroutine options
    var_dump('Coroutine Options: ', OpenSwoole\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 OpenSwoole 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 OpenSwoole 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 OpenSwoole DNS cache invalidation timeout, the default is 60 seconds.
dns_cache_capacityv4.2.11Set the OpenSwoole 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 September 20, 2022