Swoole\Coroutine::set()

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:

<?php
$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' => '8.8.8.8',
    '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;
    },
];

Swoole\Coroutine::set($options);

...

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.

<?php

// Set coroutine options before you start a server...
Swoole\Coroutine::set([
        'max_coroutine' => 800,
]);

$server = new Swoole\HTTP\Server("127.0.0.1", 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.
 *
 */
$server->set([
    //'max_coroutine' => 100,
]);

$server->on("Start", function (Swoole\Http\Server $server)
{
    echo "Swoole HTTP server  started at http://127.0.0.1:9501\n";

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

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

...

$server->start();

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_concurrency v4.7.1 The 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_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 "8.8.8.8".
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