├── LICENSE
├── README.md
├── composer.json
├── composer.lock
└── src
    ├── Pool.php
    ├── Trampoline.php
    └── functions.php


/LICENSE:
--------------------------------------------------------------------------------
 1 | BSD 3-Clause License
 2 | 
 3 | Copyright (c) 2016, Gilles Crettenand
 4 | All rights reserved.
 5 | 
 6 | Redistribution and use in source and binary forms, with or without
 7 | modification, are permitted provided that the following conditions are met:
 8 | 
 9 | * Redistributions of source code must retain the above copyright notice, this
10 |   list of conditions and the following disclaimer.
11 | 
12 | * Redistributions in binary form must reproduce the above copyright notice,
13 |   this list of conditions and the following disclaimer in the documentation
14 |   and/or other materials provided with the distribution.
15 | 
16 | * Neither the name of the copyright holder nor the names of its
17 |   contributors may be used to endorse or promote products derived from
18 |   this software without specific prior written permission.
19 | 
20 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Trampoline 
  2 | 
  3 | [![Build Status](https://travis-ci.org/functional-php/trampoline.svg)](https://travis-ci.org/functional-php/trampoline)
  4 | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/functional-php/trampoline/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/functional-php/trampoline/?branch=master)
  5 | [![Code Coverage](https://scrutinizer-ci.com/g/functional-php/trampoline/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/functional-php/trampoline/?branch=master)
  6 | [![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/functional-php/trampoline.svg)](http://isitmaintained.com/project/functional-php/trampoline "Average time to resolve an issue")
  7 | [![Percentage of issues still open](http://isitmaintained.com/badge/open/functional-php/trampoline.svg)](http://isitmaintained.com/project/functional-php/trampoline "Percentage of issues still open")
  8 | [![Chat on Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/functional-php)
  9 | 
 10 | Trampolines are a technique used to avoid blowing the call stack when doing recursive calls. This is needed because PHP does not perform tail-call optimization.
 11 | 
 12 | For more information about what is tail-call optimization (or TCO), you can read : http://stackoverflow.com/questions/310974/what-is-tail-call-optimization#answer-310980
 13 | 
 14 | For a more in depth definition of trampolines and recursion as a whole, I can recommend you read http://blog.moertel.com/posts/2013-06-12-recursion-to-iteration-4-trampolines.html which is using Python but should be easy enough to understand.
 15 | 
 16 | ## Installation
 17 | 
 18 |     composer require functional-php/trampoline
 19 | 
 20 | ## Basic Usage
 21 | 
 22 | If we have the following recursive function:
 23 | 
 24 | ```php
 25 | <?php
 26 | 
 27 | function factorial($n, $acc = 1) {
 28 |     return $n <= 1 ? $acc : factorial($n - 1, $n * $acc);
 29 | };
 30 | 
 31 | echo factorial(5);
 32 | // 120
 33 | 
 34 | ```
 35 | 
 36 | We need to simply replace the recursive call by a call to the `bounce` function:
 37 | 
 38 | ``` php
 39 | <?php
 40 | 
 41 | use FunctionalPHP\Trampoline as T;
 42 | 
 43 | function factorial($n, $acc = 1) {
 44 |     return $n <= 1 ? $acc : T\bounce('factorial', $n - 1, $n * $acc);
 45 | };
 46 | 
 47 | echo T\trampoline('factorial', 5);
 48 | // 120
 49 | 
 50 | ```
 51 | 
 52 | The `bounce` and `trampoline` functions accepts anything that is deemed a valid [`callable`](http://php.net/manual/en/language.types.callable.php) by PHP.
 53 | 
 54 | The `trampoline` function will also accept an instance of `Trampoline` created by `bounce` but will ignore any arguments in this case.
 55 | 
 56 | ## Helpers
 57 | 
 58 | You can also call statically any function from the global namespace on the `Trampoline` class if you prefer this style:
 59 | 
 60 | ``` php
 61 | <?php
 62 | 
 63 | use FunctionalPHP\Trampoline\Trampoline;
 64 | 
 65 | echo Trampoline::factorial(5);
 66 | // 120
 67 | 
 68 | echo Trampoline::strtoupper('Hello!');
 69 | // HELLO!
 70 | 
 71 | ```
 72 | 
 73 | This will however not work for functions inside a namespace.
 74 | 
 75 | If you want to have a ready to call function when using a trampoline, you can use the `trampoline_wrapper` helper. It will create a wrapper function that will call `trampoline` for you and return the result.
 76 | 
 77 | ``` php
 78 | <?php
 79 | 
 80 | use FunctionalPHP\Trampoline as T;
 81 | 
 82 | function factorial($n, $acc = 1) {
 83 |     return $n <= 1 ? $acc : T\bounce('factorial', $n - 1, $n * $acc);
 84 | };
 85 | 
 86 | $fact = T\trampoline_wrapper('factorial');
 87 | 
 88 | echo $fact(5);
 89 | // 120
 90 | 
 91 | ```
 92 | 
 93 | ## Alternative method
 94 | 
 95 | The library also contain an alternative implementation to run tail recursive function without risking a stack overflow based on an argument queue instead of a trampoline.
 96 | 
 97 | You will need to use the `$this` variable as the recursive function. Here is the factorial example using this second method.
 98 | 
 99 | ``` php
100 | <?php
101 | 
102 | use FunctionalPHP\Trampoline as T;
103 | 
104 | $fact = T\pool(function($n, $acc = 1) {
105 |     return $n <= 1 ? $acc : $this($n - 1, $n * $acc);
106 | });
107 | 
108 | echo $fact(5);
109 | // 120
110 | 
111 | ```
112 | 
113 | At this time, only anonymous functions (ie instance of the `Closure` class) are supported. But as soon as PHP 7.1 is released you will be able to use any callable.
114 | 
115 | From a performance standpoint, there is no measurable difference between the two approaches.
116 | 
117 | ## Testing
118 | 
119 | You can run the test suite for the library using:
120 | 
121 |     composer test
122 |     
123 | A test report will be available in the `reports` directory.
124 | 
125 | ## Contributing
126 | 
127 | There shouldn't be much to contribute except the potential bug but any kind of contribution are welcomed! Do not hesitate to open an issue or submit a pull request.
128 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "functional-php/trampoline",
 3 |   "description": "Trampoline implementation for PHP.",
 4 |   "keywords": ["functional", "recursion", "trampoline"],
 5 |   "license": "BSD-3-Clause",
 6 |   "authors": [
 7 |     {
 8 |       "name": "Gilles Crettenand",
 9 |       "email": "gilles@crettenand.info"
10 |     }
11 |   ],
12 |   "require": {
13 |     "php": ">=5.6.0"
14 |   },
15 |   "require-dev": {
16 |     "atoum/atoum": "*"
17 |   },
18 |   "scripts": {
19 |     "test": "./vendor/bin/atoum --enable-branch-and-path-coverage"
20 |   },
21 |   "autoload": {
22 |     "psr-4": {
23 |       "FunctionalPHP\\Trampoline\\": "./src"
24 |     },
25 |     "files": [
26 |       "src/functions.php"
27 |     ]
28 |   }
29 | }
30 | 


--------------------------------------------------------------------------------
/composer.lock:
--------------------------------------------------------------------------------
  1 | {
  2 |     "_readme": [
  3 |         "This file locks the dependencies of your project to a known state",
  4 |         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
  5 |         "This file is @generated automatically"
  6 |     ],
  7 |     "hash": "fa85b093f9a3b24d21cc4a54de800fd8",
  8 |     "content-hash": "dd1f0ee41bff90f5547d51c68c9b3f54",
  9 |     "packages": [],
 10 |     "packages-dev": [
 11 |         {
 12 |             "name": "atoum/atoum",
 13 |             "version": "2.8.2",
 14 |             "source": {
 15 |                 "type": "git",
 16 |                 "url": "https://github.com/atoum/atoum.git",
 17 |                 "reference": "4d0136b21185eea5fc2ee638f77b291e6c537100"
 18 |             },
 19 |             "dist": {
 20 |                 "type": "zip",
 21 |                 "url": "https://api.github.com/repos/atoum/atoum/zipball/4d0136b21185eea5fc2ee638f77b291e6c537100",
 22 |                 "reference": "4d0136b21185eea5fc2ee638f77b291e6c537100",
 23 |                 "shasum": ""
 24 |             },
 25 |             "require": {
 26 |                 "ext-hash": "*",
 27 |                 "ext-json": "*",
 28 |                 "ext-session": "*",
 29 |                 "ext-tokenizer": "*",
 30 |                 "ext-xml": "*",
 31 |                 "php": ">=5.3.3"
 32 |             },
 33 |             "replace": {
 34 |                 "mageekguy/atoum": "*"
 35 |             },
 36 |             "suggest": {
 37 |                 "atoum/stubs": "Provides IDE support (like autocompletion) for atoum",
 38 |                 "ext-mbstring": "Provides support for UTF-8 strings"
 39 |             },
 40 |             "bin": [
 41 |                 "bin/atoum"
 42 |             ],
 43 |             "type": "library",
 44 |             "extra": {
 45 |                 "branch-alias": {
 46 |                     "dev-master": "2.x-dev"
 47 |                 }
 48 |             },
 49 |             "autoload": {
 50 |                 "classmap": [
 51 |                     "classes/"
 52 |                 ]
 53 |             },
 54 |             "notification-url": "https://packagist.org/downloads/",
 55 |             "license": [
 56 |                 "BSD-3-Clause"
 57 |             ],
 58 |             "authors": [
 59 |                 {
 60 |                     "name": "Frédéric Hardy",
 61 |                     "email": "frederic.hardy@atoum.org",
 62 |                     "homepage": "http://blog.mageekbox.net"
 63 |                 },
 64 |                 {
 65 |                     "name": "François Dussert",
 66 |                     "email": "francois.dussert@atoum.org"
 67 |                 },
 68 |                 {
 69 |                     "name": "Gérald Croes",
 70 |                     "email": "gerald.croes@atoum.org"
 71 |                 },
 72 |                 {
 73 |                     "name": "Julien Bianchi",
 74 |                     "email": "julien.bianchi@atoum.org"
 75 |                 },
 76 |                 {
 77 |                     "name": "Ludovic Fleury",
 78 |                     "email": "ludovic.fleury@atoum.org"
 79 |                 }
 80 |             ],
 81 |             "description": "Simple modern and intuitive unit testing framework for PHP 5.3+",
 82 |             "homepage": "http://www.atoum.org",
 83 |             "keywords": [
 84 |                 "TDD",
 85 |                 "atoum",
 86 |                 "test",
 87 |                 "unit testing"
 88 |             ],
 89 |             "time": "2016-08-12 13:45:10"
 90 |         }
 91 |     ],
 92 |     "aliases": [],
 93 |     "minimum-stability": "stable",
 94 |     "stability-flags": [],
 95 |     "prefer-stable": true,
 96 |     "prefer-lowest": false,
 97 |     "platform": [],
 98 |     "platform-dev": []
 99 | }
100 | 


--------------------------------------------------------------------------------
/src/Pool.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace FunctionalPHP\Trampoline;
 4 | 
 5 | class Pool
 6 | {
 7 |     /** @var  callable|\Closure $f */
 8 |     private $f;
 9 | 
10 |     /** @var  array $arguments_pool */
11 |     private $arguments_pool = [];
12 | 
13 |     /** @var bool currently recursing */
14 |     private $recursing = false;
15 | 
16 |     /**
17 |      * @param callable $f
18 |      */
19 |     protected function __construct(callable $f)
20 |     {
21 |         if($f instanceof \Closure) {
22 |             $this->f = $f->bindTo($this);
23 |         } elseif(method_exists('\Closure','fromCallable')) {
24 |             $this->f = \Closure::fromCallable($f)->bindTo($this);
25 |         } else {
26 |             throw new \RuntimeException('Using anything else than a callable is only possible for PHP >= 7.1.');
27 |         }
28 |     }
29 | 
30 |     /**
31 |      * Invoke the stored function with the stored arguments.
32 |      *
33 |      * @return mixed
34 |      */
35 |     public function __invoke()
36 |     {
37 |         $result = null;
38 |         $this->arguments_pool[] = func_get_args();
39 | 
40 |         if($this->recursing === false) {
41 |             $this->recursing = true;
42 | 
43 |             while(! empty($this->arguments_pool)) {
44 |                 $result = call_user_func_array($this->f, array_shift($this->arguments_pool));
45 |             }
46 | 
47 |             $this->recursing = false;
48 |         }
49 | 
50 |         return $result;
51 |     }
52 | 
53 |     /**
54 |      * @param callable $f
55 |      * @return callable
56 |      */
57 |     public static function get(callable $f)
58 |     {
59 |         return new static($f);
60 |     }
61 | }
62 | 


--------------------------------------------------------------------------------
/src/Trampoline.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace FunctionalPHP\Trampoline;
 4 | 
 5 | class Trampoline
 6 | {
 7 |     /** @var  callable $f */
 8 |     private $f;
 9 | 
10 |     /** @var  array $args */
11 |     private $args;
12 | 
13 |     /**
14 |      * @param callable $f
15 |      * @param array $args
16 |      */
17 |     protected function __construct(callable $f, array $args = array())
18 |     {
19 |         $this->f = $f;
20 |         $this->args = $args;
21 |     }
22 | 
23 |     /**
24 |      * Invoke the stored function with the stored arguments.
25 |      *
26 |      * @return mixed
27 |      */
28 |     public function __invoke()
29 |     {
30 |         return call_user_func_array($this->f, $this->args);
31 |     }
32 | 
33 |     /**
34 |      * Create a new trampoline instance for the given function and arguments.
35 |      *
36 |      * @param callable $f
37 |      * @param array ...$args
38 |      * @return static|callable
39 |      */
40 |     public static function bounce(callable $f, ...$args)
41 |     {
42 |         return new static($f, $args);
43 |     }
44 | 
45 |     /**
46 |      * Run a callable or a Trampoline until it gets to the final result
47 |      * (ie: not a Trampoline instance)
48 |      *
49 |      * @param callable|Trampoline $f
50 |      * @param array ...$args
51 |      * @return mixed
52 |      */
53 |     public static function run($f, ...$args)
54 |     {
55 |         if($f instanceof self) {
56 |             $return = $f;
57 |         } else if(is_callable($f)) {
58 |             $return = call_user_func_array($f, $args);
59 |         } else  {
60 |             throw new \RuntimeException('Expected a callable or an instance of Trampoline.');
61 |         }
62 | 
63 |         while($return instanceof self) {
64 |             $return = $return();
65 |         }
66 | 
67 |         return $return;
68 |     }
69 | 
70 |     /**
71 |      * Helper function to easily run a callable as a Trampoline.
72 |      *
73 |      * @param string $name
74 |      * @param array $arguments
75 |      * @return mixed
76 |      */
77 |     public static function __callStatic($name, $arguments)
78 |     {
79 |         return static::run($name, ...$arguments);
80 |     }
81 | }


--------------------------------------------------------------------------------
/src/functions.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace FunctionalPHP\Trampoline;
 4 | 
 5 | /**
 6 |  * This method should be used inside your recursive functions
 7 |  * when you need to make a tail recursive call.
 8 |  *
 9 |  * Instead of calling the function directly it will give back
10 |  * the control to the trampoline which will in turn call your
11 |  * function again in order to avoid a stack overflow.
12 |  *
13 |  * @param callable $f a tail recursive function
14 |  * @param array ...$args arguments for the function
15 |  * @return callable a callable for the Trampoline
16 |  */
17 | function bounce(callable $f, ...$args)
18 | {
19 |     return Trampoline::bounce($f, ...$args);
20 | }
21 | 
22 | /**
23 |  * Launch a trampoline. The given callable should be a tail
24 |  * recursive function.
25 |  *
26 |  * All recursive calls inside the function should be made
27 |  * using the bounce function so that the trampoline can
28 |  * correctly avoid stack overflows.
29 |  *
30 |  * @param callable $f a tail recursive function
31 |  * @param array ...$args arguments for the function
32 |  * @return mixed The final result of your function
33 |  */
34 | function trampoline(callable $f, ...$args)
35 | {
36 |     return Trampoline::run($f, ...$args);
37 | }
38 | 
39 | function trampoline_wrapper(callable $f)
40 | {
41 |     return function(...$args) use($f) {
42 |         return Trampoline::run($f, ...$args);
43 |     };
44 | }
45 | 
46 | /**
47 |  * Alternative method to get a tail recursive function
48 |  * without risk of stack overflows.
49 |  *
50 |  * All recursive calls inside the function should be made
51 |  * by using the `$this` directly as a function.
52 |  *
53 |  * @param callable $f a tail recursive function
54 |  * @return callable equivalent function without stack overflow risk
55 |  */
56 | function pool(callable $f)
57 | {
58 |     return Pool::get($f);
59 | }
60 | 


--------------------------------------------------------------------------------