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_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

Name Available From Description
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_level v4.0.0 Set the log level debug output
trace_flags v4.0.0 Decide which logs you want to track, reduce the number of logs thrown by only selecting what you want to log.
socket_connect_timeout v4.2.10 Set the TCP connection timeout when establishing a connection, sending or receiving data.
socket_read_timeout v4.3.0 Set the TCP read timeout.
socket_write_timeout v4.3.0 Set the TCP write timeout.
socket_dns_timeout v4.4.0 Set the Domain name resolution timeout.
socket_timeout v4.2.10 Set the send or receive timeout for a socket connection.
dns_cache_expire v4.2.11 Set the Swoole DNS cache invalidation timeout, the default is 60 seconds.
dns_cache_capacity v4.2.11 Set the Swoole DNS cache capacity, the default is 1000K.
hook_flags v4.4.0 Coroutine-based hook configuration, set which coroutine hooks you want to enable.
enable_preemptive_scheduler v4.4.0 Set when to coroutine preemptive scheduling, the maximum execution time of the coroutine is 10ms, which will overwrite the ini configuration.
dns_server v4.5.0 Set the server for dns query, the default is "".
exit_condition v4.5.0 Pass a callable and customize reactor exit conditions by returning true or false.
enable_deadlock_check v4.6.0 Set whether to enable coroutine deadlock detection, enabled by default
deadlock_check_disable_trace v4.6.0 Set whether to output stack frames for coroutine deadlock detection
deadlock_check_limit v4.6.0 Limit the maximum number of outputs during coroutine deadlock detection
deadlock_check_depth v4.6.0 Limit the number of stack frames returned during coroutine deadlock detection