Merge "Special:Upload should not crash on failing previews"
[mediawiki.git] / includes / libs / MemoizedCallable.php
blob12a5cadb993f22354dd6e458654d699c52aaff96
1 <?php
2 /**
3 * APC-backed and APCu-backed function memoization
5 * This class provides memoization for pure functions. A function is pure
6 * if its result value depends on nothing other than its input parameters
7 * and if invoking it does not cause any side-effects.
9 * The first invocation of the memoized callable with a particular set of
10 * arguments will be delegated to the underlying callable. Repeat invocations
11 * with the same input parameters will be served from APC or APCu.
13 * @par Example:
14 * @code
15 * $memoizedStrrev = new MemoizedCallable( 'range' );
16 * $memoizedStrrev->invoke( 5, 8 ); // result: array( 5, 6, 7, 8 )
17 * $memoizedStrrev->invokeArgs( array( 5, 8 ) ); // same
18 * MemoizedCallable::call( 'range', array( 5, 8 ) ); // same
19 * @endcode
21 * This program is free software; you can redistribute it and/or modify
22 * it under the terms of the GNU General Public License as published by
23 * the Free Software Foundation; either version 2 of the License, or
24 * (at your option) any later version.
26 * This program is distributed in the hope that it will be useful,
27 * but WITHOUT ANY WARRANTY; without even the implied warranty of
28 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
29 * GNU General Public License for more details.
31 * You should have received a copy of the GNU General Public License along
32 * with this program; if not, write to the Free Software Foundation, Inc.,
33 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
34 * http://www.gnu.org/copyleft/gpl.html
36 * @file
37 * @author Ori Livneh
38 * @since 1.27
40 class MemoizedCallable {
42 /** @var callable */
43 private $callable;
45 /** @var string Unique name of callable; used for cache keys. */
46 private $callableName;
48 /**
49 * Constructor.
51 * @throws InvalidArgumentException if $callable is not a callable.
52 * @param callable $callable Function or method to memoize.
53 * @param int $ttl TTL in seconds. Defaults to 3600 (1hr). Capped at 86400 (24h).
55 public function __construct( $callable, $ttl = 3600 ) {
56 if ( !is_callable( $callable, false, $this->callableName ) ) {
57 throw new InvalidArgumentException(
58 'Argument 1 passed to MemoizedCallable::__construct() must ' .
59 'be an instance of callable; ' . gettype( $callable ) . ' given'
63 if ( $this->callableName === 'Closure::__invoke' ) {
64 // Differentiate anonymous functions from one another
65 $this->callableName .= uniqid();
68 $this->callable = $callable;
69 $this->ttl = min( max( $ttl, 1 ), 86400 );
72 /**
73 * Fetch the result of a previous invocation from APC or APCu.
75 * @param string $key
76 * @param bool &$success
78 protected function fetchResult( $key, &$success ) {
79 $success = false;
80 if ( function_exists( 'apc_fetch' ) ) {
81 return apc_fetch( $key, $success );
82 } elseif ( function_exists( 'apcu_fetch' ) ) {
83 return apcu_fetch( $key, $success );
85 return false;
88 /**
89 * Store the result of an invocation in APC or APCu.
91 * @param string $key
92 * @param mixed $result
94 protected function storeResult( $key, $result ) {
95 if ( function_exists( 'apc_store' ) ) {
96 apc_store( $key, $result, $this->ttl );
97 } elseif ( function_exists( 'apcu_store' ) ) {
98 apcu_store( $key, $result, $this->ttl );
103 * Invoke the memoized function or method.
105 * @throws InvalidArgumentException If parameters list contains non-scalar items.
106 * @param array $args Parameters for memoized function or method.
107 * @return mixed The memoized callable's return value.
109 public function invokeArgs( array $args = [] ) {
110 foreach ( $args as $arg ) {
111 if ( $arg !== null && !is_scalar( $arg ) ) {
112 throw new InvalidArgumentException(
113 'MemoizedCallable::invoke() called with non-scalar ' .
114 'argument'
119 $hash = md5( serialize( $args ) );
120 $key = __CLASS__ . ':' . $this->callableName . ':' . $hash;
121 $success = false;
122 $result = $this->fetchResult( $key, $success );
123 if ( !$success ) {
124 $result = call_user_func_array( $this->callable, $args );
125 $this->storeResult( $key, $result );
128 return $result;
132 * Invoke the memoized function or method.
134 * Like MemoizedCallable::invokeArgs(), but variadic.
136 * @param mixed ...$params Parameters for memoized function or method.
137 * @return mixed The memoized callable's return value.
139 public function invoke() {
140 return $this->invokeArgs( func_get_args() );
144 * Shortcut method for creating a MemoizedCallable and invoking it
145 * with the specified arguments.
147 * @param callable $callable
148 * @param array $args
149 * @param int $ttl
151 public static function call( $callable, array $args = [], $ttl = 3600 ) {
152 $instance = new self( $callable, $ttl );
153 return $instance->invokeArgs( $args );