Utopia Balancer

Utopia Balancer library is simple and lite library for balancing choices between multiple options. This library is aiming to be as simple and easy to learn and use. This library is maintained by the Appwrite team.

Although this library is part of the Utopia Framework project it is dependency free and can be used as standalone with any other PHP project or framework.

Getting Started

Install using composer:

composer require utopia-php/balancer

Balancer supports multiple algorithms. Each picks option differently, and may have different set of methods available for configuration.

Balancer Algorithms

1. Random

Random algorithm pick option randomly. The same option could be picked multiple times in a row. Example:

<?phprequire_once'../vendor/autoload.php';
useUtopia\Balancer\Algorithm\Random;
useUtopia\Balancer\Balancer;
useUtopia\Balancer\Option;
$balancer = newBalancer(newRandom());
$balancer->addFilter(fn (Option$option) => $option->getState('online', false) === true);
$balancer
->addOption(newOption([ 'hostname' => 'proxy-1', 'online' => true ]))
->addOption(newOption([ 'hostname' => 'proxy-2', 'online' => false ]))
->addOption(newOption([ 'hostname' => 'proxy-3', 'online' => true ]));
var_dump($balancer->run());
var_dump($balancer->run());
var_dump($balancer->run());

2. First and Last

First algorithm always picks first option. Similiarly, Last algorithm always picks last option. Example:

<?phprequire_once'../vendor/autoload.php';
useUtopia\Balancer\Algorithm\First;
useUtopia\Balancer\Algorithm\Last;
useUtopia\Balancer\Balancer;
useUtopia\Balancer\Option;
$balancer = newBalancer(newFirst());
$balancer
->addOption(newOption([ 'runtime' => 'PHP' ]))
->addOption(newOption([ 'runtime' => 'JavaScript' ]))
->addOption(newOption([ 'runtime' => 'Java' ]));
var_dump($balancer->run());
$balancer = newBalancer(newLast());
$balancer
->addOption(newOption([ 'runtime' => 'PHP' ]))
->addOption(newOption([ 'runtime' => 'JavaScript' ]))
->addOption(newOption([ 'runtime' => 'Java' ]));
var_dump($balancer->run());

3. Round Robin

RoundRobin algorithm cycles over all options starting first. Once algorithm cycles over all options, it resets back to the beginning. Example:

<?phprequire_once'../vendor/autoload.php';
useUtopia\Balancer\Algorithm\RoundRobin;
useUtopia\Balancer\Balancer;
useUtopia\Balancer\Option;
$balancer = newBalancer(newRoundRobin(-1));
$balancer->addFilter(fn (Option$option) => $option->getState('online', false) === true);
$balancer
->addOption(newOption([ 'dataCenter' => 'fra-1' ]))
->addOption(newOption([ 'dataCenter' => 'fra-2' ]))
->addOption(newOption([ 'dataCenter' => 'lon-1' ]));
var_dump($balancer->run()); // fra-1var_dump($balancer->run()); // fra-2var_dump($balancer->run()); // lon-1var_dump($balancer->run()); // fra-1var_dump($balancer->run()); // fra-2

When using RoundRobin in concurrency model, make sure to store index in atomic way. Example:

<?phprequire_once'../vendor/autoload.php';
useUtopia\Balancer\Algorithm\RoundRobin;
useUtopia\Balancer\Balancer;
useUtopia\Balancer\Option;
$atomic = newAtomic(-1); // Some atomic implementation, for example: https://openswoole.com/docs/modules/swoole-atomicfunctiononRequest() {
$lastIndex = $atomic->get();
$algo = newRoundRobin($lastIndex);
$balancer = newBalancer();
$balancer->addFilter(fn (Option$option) => $option->getState('online', false) === true);
$balancer
->addOption(newOption([ 'dataCenter' => 'fra-1' ]))
->addOption(newOption([ 'dataCenter' => 'fra-2' ]))
->addOption(newOption([ 'dataCenter' => 'lon-1' ]));
var_dump($balancer->run());
$atomic->cmpset($lastIndex, $algo->getIndex());
}

Balancer Group

If balancer filters cause balancer to have no options to pick from, null will be returned. More often then not, you will need a backup logic for this scenario. You can use Group to create a group of multiple balancers and if one fails, next can be used as fallback. Notice Group tries balances in order you added them.

<?phprequire_once'../vendor/autoload.php';
useUtopia\Balancer\Algorithm\First;
useUtopia\Balancer\Balancer;
useUtopia\Balancer\Group;
useUtopia\Balancer\Option;
// Prepare options where each has high CPU load$options = [
newOption([ 'dataCenter' => 'fra-1', 'cpu' => 91 ]),
newOption([ 'dataCenter' => 'fra-2', 'cpu' => 95 ]),
newOption([ 'dataCenter' => 'lon-1', 'cpu' => 87 ]),
];
// Prepare balancer that allows only low CPU load options$balancer1 = newBalancer(newFirst());
$balancer1->addFilter(fn ($option) => $option->getState('cpu') < 80);
// Prepare balancer that allows all options$balancer2 = newBalancer(newFirst());
// Add options to both balancersforeach ($optionsas$option) {
$balancer1->addOption($option);
$balancer2->addOption($option);
}
// Prepare group with both balancers$group = newGroup();
$group
->add($balancer1)
->add($balancer2);
// Run group to get option$option = $group->run() ?? newOption([]);
\var_dump($option);
// We got fra-1 option. First balancer filtered out all options, but second balancer allowed any, and First algorithm picked first option

System Requirements

Utopia Framework requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php