utopia-php / balancer
A simple library to balance choices between multiple options.
Requires
- php: >=8.0
Requires (Dev)
- laravel/pint: 1.2.*
- phpstan/phpstan: 1.8.*
- phpunit/phpunit: ^9.3
This package is auto-updated.
Last update: 2024-11-07 13:14:24 UTC
README
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
- Random
Random
algorithm pick option randomly. The same option could be picked multiple times in a row. Example:
<?php require_once '../vendor/autoload.php'; use Utopia\Balancer\Algorithm\Random; use Utopia\Balancer\Balancer; use Utopia\Balancer\Option; $balancer = new Balancer(new Random()); $balancer->addFilter(fn (Option $option) => $option->getState('online', false) === true); $balancer ->addOption(new Option([ 'hostname' => 'proxy-1', 'online' => true ])) ->addOption(new Option([ 'hostname' => 'proxy-2', 'online' => false ])) ->addOption(new Option([ 'hostname' => 'proxy-3', 'online' => true ])); var_dump($balancer->run()); var_dump($balancer->run()); var_dump($balancer->run());
- First and Last
First
algorithm always picks first option. Similiarly, Last
algorithm always picks last option. Example:
<?php require_once '../vendor/autoload.php'; use Utopia\Balancer\Algorithm\First; use Utopia\Balancer\Algorithm\Last; use Utopia\Balancer\Balancer; use Utopia\Balancer\Option; $balancer = new Balancer(new First()); $balancer ->addOption(new Option([ 'runtime' => 'PHP' ])) ->addOption(new Option([ 'runtime' => 'JavaScript' ])) ->addOption(new Option([ 'runtime' => 'Java' ])); var_dump($balancer->run()); $balancer = new Balancer(new Last()); $balancer ->addOption(new Option([ 'runtime' => 'PHP' ])) ->addOption(new Option([ 'runtime' => 'JavaScript' ])) ->addOption(new Option([ 'runtime' => 'Java' ])); var_dump($balancer->run());
- Round Robin
RoundRobin
algorithm cycles over all options starting first. Once algorithm cycles over all options, it resets back to the beginning. Example:
<?php require_once '../vendor/autoload.php'; use Utopia\Balancer\Algorithm\RoundRobin; use Utopia\Balancer\Balancer; use Utopia\Balancer\Option; $balancer = new Balancer(new RoundRobin(-1)); $balancer->addFilter(fn (Option $option) => $option->getState('online', false) === true); $balancer ->addOption(new Option([ 'dataCenter' => 'fra-1' ])) ->addOption(new Option([ 'dataCenter' => 'fra-2' ])) ->addOption(new Option([ 'dataCenter' => 'lon-1' ])); var_dump($balancer->run()); // fra-1 var_dump($balancer->run()); // fra-2 var_dump($balancer->run()); // lon-1 var_dump($balancer->run()); // fra-1 var_dump($balancer->run()); // fra-2
When using RoundRobin
in concurrency model, make sure to store index in atomic way. Example:
<?php require_once '../vendor/autoload.php'; use Utopia\Balancer\Algorithm\RoundRobin; use Utopia\Balancer\Balancer; use Utopia\Balancer\Option; $atomic = new Atomic(-1); // Some atomic implementation, for example: https://openswoole.com/docs/modules/swoole-atomic function onRequest() { $lastIndex = $atomic->get(); $algo = new RoundRobin($lastIndex); $balancer = new Balancer(); $balancer->addFilter(fn (Option $option) => $option->getState('online', false) === true); $balancer ->addOption(new Option([ 'dataCenter' => 'fra-1' ])) ->addOption(new Option([ 'dataCenter' => 'fra-2' ])) ->addOption(new Option([ '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.
<?php require_once '../vendor/autoload.php'; use Utopia\Balancer\Algorithm\First; use Utopia\Balancer\Balancer; use Utopia\Balancer\Group; use Utopia\Balancer\Option; // Prepare options where each has high CPU load $options = [ new Option([ 'dataCenter' => 'fra-1', 'cpu' => 91 ]), new Option([ 'dataCenter' => 'fra-2', 'cpu' => 95 ]), new Option([ 'dataCenter' => 'lon-1', 'cpu' => 87 ]), ]; // Prepare balancer that allows only low CPU load options $balancer1 = new Balancer(new First()); $balancer1->addFilter(fn ($option) => $option->getState('cpu') < 80); // Prepare balancer that allows all options $balancer2 = new Balancer(new First()); // Add options to both balancers foreach ($options as $option) { $balancer1->addOption($option); $balancer2->addOption($option); } // Prepare group with both balancers $group = new Group(); $group ->add($balancer1) ->add($balancer2); // Run group to get option $option = $group->run() ?? new Option([]); \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