includes/libs/objectcache/MemcachedPeclBagOStuff.php

   1 <?php
   2 /**
   3  * Object caching using memcached.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Cache
  22  */
  23
  24 /**
  25  * A wrapper class for the PECL memcached client
  26  *
  27  * @ingroup Cache
  28  */
  29 class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
  30         /** @var Memcached */
  31         protected $client;
  32
  33         /**
  34          * Available parameters are:
  35          *   - servers:              List of IP:port combinations holding the memcached servers.
  36          *   - persistent:           Whether to use a persistent connection
  37          *   - compress_threshold:   The minimum size an object must be before it is compressed
  38          *   - timeout:              The read timeout in microseconds
  39          *   - connect_timeout:      The connect timeout in seconds
  40          *   - retry_timeout:        Time in seconds to wait before retrying a failed connect attempt
  41          *   - server_failure_limit: Limit for server connect failures before it is removed
  42          *   - serializer:           Either "php" or "igbinary". Igbinary produces more compact
  43          *                           values, but serialization is much slower unless the php.ini
  44          *                           option igbinary.compact_strings is off.
  45          *   - use_binary_protocol   Whether to enable the binary protocol (default is ASCII)
  46          *   - allow_tcp_nagle_delay Whether to permit Nagle's algorithm for reducing packet count
  47          * @param array $params
  48          */
  49         function __construct( $params ) {
  50                 parent::__construct( $params );
  51
  52                 // Default class-specific parameters
  53                 $params += [
  54                         'compress_threshold' => 1500,
  55                         'connect_timeout' => 0.5,
  56                         'serializer' => 'php',
  57                         'use_binary_protocol' => false,
  58                         'allow_tcp_nagle_delay' => true
  59                 ];
  60
  61                 if ( $params['persistent'] ) {
  62                         // The pool ID must be unique to the server/option combination.
  63                         // The Memcached object is essentially shared for each pool ID.
  64                         // We can only reuse a pool ID if we keep the config consistent.
  65                         $connectionPoolId = md5( serialize( $params ) );
  66                         $client = new Memcached( $connectionPoolId );
  67                         $this->initializeClient( $client, $params );
  68                 } else {
  69                         $client = new Memcached;
  70                         $this->initializeClient( $client, $params );
  71                 }
  72
  73                 $this->client = $client;
  74
  75                 // The compression threshold is an undocumented php.ini option for some
  76                 // reason. There's probably not much harm in setting it globally, for
  77                 // compatibility with the settings for the PHP client.
  78                 ini_set( 'memcached.compression_threshold', $params['compress_threshold'] );
  79         }
  80
  81         /**
  82          * Initialize the client only if needed and reuse it otherwise.
  83          * This avoids duplicate servers in the list and new connections.
  84          *
  85          * @param Memcached $client
  86          * @param array $params
  87          * @throws RuntimeException
  88          */
  89         private function initializeClient( Memcached $client, array $params ) {
  90                 if ( $client->getServerList() ) {
  91                         $this->logger->debug( __METHOD__ . ": pre-initialized client instance." );
  92
  93                         return; // preserve persistent handle
  94                 }
  95
  96                 $this->logger->debug( __METHOD__ . ": initializing new client instance." );
  97
  98                 $options = [
  99                         // Network protocol (ASCII or binary)
 100                         Memcached::OPT_BINARY_PROTOCOL => $params['use_binary_protocol'],
 101                         // Set various network timeouts
 102                         Memcached::OPT_CONNECT_TIMEOUT => $params['connect_timeout'] * 1000,
 103                         Memcached::OPT_SEND_TIMEOUT => $params['timeout'],
 104                         Memcached::OPT_RECV_TIMEOUT => $params['timeout'],
 105                         Memcached::OPT_POLL_TIMEOUT => $params['timeout'] / 1000,
 106                         // Avoid pointless delay when sending/fetching large blobs
 107                         Memcached::OPT_TCP_NODELAY => !$params['allow_tcp_nagle_delay'],
 108                         // Set libketama mode since it's recommended by the documentation
 109                         Memcached::OPT_LIBKETAMA_COMPATIBLE => true
 110                 ];
 111                 if ( isset( $params['retry_timeout'] ) ) {
 112                         $options[Memcached::OPT_RETRY_TIMEOUT] = $params['retry_timeout'];
 113                 }
 114                 if ( isset( $params['server_failure_limit'] ) ) {
 115                         $options[Memcached::OPT_SERVER_FAILURE_LIMIT] = $params['server_failure_limit'];
 116                 }
 117                 if ( $params['serializer'] === 'php' ) {
 118                         $options[Memcached::OPT_SERIALIZER] = Memcached::SERIALIZER_PHP;
 119                 } elseif ( $params['serializer'] === 'igbinary' ) {
 120                         if ( !Memcached::HAVE_IGBINARY ) {
 121                                 throw new RuntimeException(
 122                                         __CLASS__ . ': the igbinary extension is not available ' .
 123                                         'but igbinary serialization was requested.'
 124                                 );
 125                         }
 126                         $options[Memcached::OPT_SERIALIZER] = Memcached::SERIALIZER_IGBINARY;
 127                 }
 128
 129                 if ( !$client->setOptions( $options ) ) {
 130                         throw new RuntimeException(
 131                                 "Invalid options: " . json_encode( $options, JSON_PRETTY_PRINT )
 132                         );
 133                 }
 134
 135                 $servers = [];
 136                 foreach ( $params['servers'] as $host ) {
 137                         if ( preg_match( '/^\[(.+)\]:(\d+)$/', $host, $m ) ) {
 138                                 $servers[] = [ $m[1], (int)$m[2] ]; // (ip, port)
 139                         } elseif ( preg_match( '/^([^:]+):(\d+)$/', $host, $m ) ) {
 140                                 $servers[] = [ $m[1], (int)$m[2] ]; // (ip or path, port)
 141                         } else {
 142                                 $servers[] = [ $host, false ]; // (ip or path, port)
 143                         }
 144                 }
 145
 146                 if ( !$client->addServers( $servers ) ) {
 147                         throw new RuntimeException( "Failed to inject server address list" );
 148                 }
 149         }
 150
 151         protected function doGet( $key, $flags = 0, &$casToken = null ) {
 152                 $this->debug( "get($key)" );
 153                 if ( defined( Memcached::class . '::GET_EXTENDED' ) ) { // v3.0.0
 154                         /** @noinspection PhpUndefinedClassConstantInspection */
 155                         $flags = Memcached::GET_EXTENDED;
 156                         $res = $this->client->get( $this->validateKeyEncoding( $key ), null, $flags );
 157                         if ( is_array( $res ) ) {
 158                                 $result = $res['value'];
 159                                 $casToken = $res['cas'];
 160                         } else {
 161                                 $result = false;
 162                                 $casToken = null;
 163                         }
 164                 } else {
 165                         $result = $this->client->get( $this->validateKeyEncoding( $key ), null, $casToken );
 166                 }
 167                 $result = $this->checkResult( $key, $result );
 168                 return $result;
 169         }
 170
 171         protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
 172                 $this->debug( "set($key)" );
 173                 $result = $this->client->set(
 174                         $this->validateKeyEncoding( $key ),
 175                         $value,
 176                         $this->fixExpiry( $exptime )
 177                 );
 178                 if ( $result === false && $this->client->getResultCode() === Memcached::RES_NOTSTORED ) {
 179                         // "Not stored" is always used as the mcrouter response with AllAsyncRoute
 180                         return true;
 181                 }
 182                 return $this->checkResult( $key, $result );
 183         }
 184
 185         protected function cas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) {
 186                 $this->debug( "cas($key)" );
 187                 $result = $this->client->cas( $casToken, $this->validateKeyEncoding( $key ),
 188                         $value, $this->fixExpiry( $exptime ) );
 189                 return $this->checkResult( $key, $result );
 190         }
 191
 192         protected function doDelete( $key, $flags = 0 ) {
 193                 $this->debug( "delete($key)" );
 194                 $result = $this->client->delete( $this->validateKeyEncoding( $key ) );
 195                 if ( $result === false && $this->client->getResultCode() === Memcached::RES_NOTFOUND ) {
 196                         // "Not found" is counted as success in our interface
 197                         return true;
 198                 }
 199                 return $this->checkResult( $key, $result );
 200         }
 201
 202         public function add( $key, $value, $exptime = 0, $flags = 0 ) {
 203                 $this->debug( "add($key)" );
 204                 $result = $this->client->add(
 205                         $this->validateKeyEncoding( $key ),
 206                         $value,
 207                         $this->fixExpiry( $exptime )
 208                 );
 209                 return $this->checkResult( $key, $result );
 210         }
 211
 212         public function incr( $key, $value = 1 ) {
 213                 $this->debug( "incr($key)" );
 214                 $result = $this->client->increment( $key, $value );
 215                 return $this->checkResult( $key, $result );
 216         }
 217
 218         public function decr( $key, $value = 1 ) {
 219                 $this->debug( "decr($key)" );
 220                 $result = $this->client->decrement( $key, $value );
 221                 return $this->checkResult( $key, $result );
 222         }
 223
 224         /**
 225          * Check the return value from a client method call and take any necessary
 226          * action. Returns the value that the wrapper function should return. At
 227          * present, the return value is always the same as the return value from
 228          * the client, but some day we might find a case where it should be
 229          * different.
 230          *
 231          * @param string $key The key used by the caller, or false if there wasn't one.
 232          * @param mixed $result The return value
 233          * @return mixed
 234          */
 235         protected function checkResult( $key, $result ) {
 236                 if ( $result !== false ) {
 237                         return $result;
 238                 }
 239                 switch ( $this->client->getResultCode() ) {
 240                         case Memcached::RES_SUCCESS:
 241                                 break;
 242                         case Memcached::RES_DATA_EXISTS:
 243                         case Memcached::RES_NOTSTORED:
 244                         case Memcached::RES_NOTFOUND:
 245                                 $this->debug( "result: " . $this->client->getResultMessage() );
 246                                 break;
 247                         default:
 248                                 $msg = $this->client->getResultMessage();
 249                                 $logCtx = [];
 250                                 if ( $key !== false ) {
 251                                         $server = $this->client->getServerByKey( $key );
 252                                         $logCtx['memcached-server'] = "{$server['host']}:{$server['port']}";
 253                                         $logCtx['memcached-key'] = $key;
 254                                         $msg = "Memcached error for key \"{memcached-key}\" on server \"{memcached-server}\": $msg";
 255                                 } else {
 256                                         $msg = "Memcached error: $msg";
 257                                 }
 258                                 $this->logger->error( $msg, $logCtx );
 259                                 $this->setLastError( BagOStuff::ERR_UNEXPECTED );
 260                 }
 261                 return $result;
 262         }
 263
 264         protected function doGetMulti( array $keys, $flags = 0 ) {
 265                 $this->debug( 'getMulti(' . implode( ', ', $keys ) . ')' );
 266                 foreach ( $keys as $key ) {
 267                         $this->validateKeyEncoding( $key );
 268                 }
 269                 $result = $this->client->getMulti( $keys ) ?: [];
 270                 return $this->checkResult( false, $result );
 271         }
 272
 273         protected function doSetMulti( array $data, $exptime = 0, $flags = 0 ) {
 274                 $this->debug( 'setMulti(' . implode( ', ', array_keys( $data ) ) . ')' );
 275                 foreach ( array_keys( $data ) as $key ) {
 276                         $this->validateKeyEncoding( $key );
 277                 }
 278                 $result = $this->client->setMulti( $data, $this->fixExpiry( $exptime ) );
 279                 return $this->checkResult( false, $result );
 280         }
 281
 282         protected function doDeleteMulti( array $keys, $flags = 0 ) {
 283                 $this->debug( 'deleteMulti(' . implode( ', ', $keys ) . ')' );
 284                 foreach ( $keys as $key ) {
 285                         $this->validateKeyEncoding( $key );
 286                 }
 287                 $result = $this->client->deleteMulti( $keys ) ?: [];
 288                 $ok = true;
 289                 foreach ( $result as $code ) {
 290                         if ( !in_array( $code, [ true, Memcached::RES_NOTFOUND ], true ) ) {
 291                                 // "Not found" is counted as success in our interface
 292                                 $ok = false;
 293                         }
 294                 }
 295                 return $this->checkResult( false, $ok );
 296         }
 297
 298         protected function doChangeTTL( $key, $exptime, $flags ) {
 299                 $this->debug( "touch($key)" );
 300                 $result = $this->client->touch( $key, $exptime );
 301                 return $this->checkResult( $key, $result );
 302         }
 303
 304         protected function serialize( $value ) {
 305                 if ( is_int( $value ) ) {
 306                         return $value;
 307                 }
 308
 309                 $serializer = $this->client->getOption( Memcached::OPT_SERIALIZER );
 310                 if ( $serializer === Memcached::SERIALIZER_PHP ) {
 311                         return serialize( $value );
 312                 } elseif ( $serializer === Memcached::SERIALIZER_IGBINARY ) {
 313                         return igbinary_serialize( $value );
 314                 }
 315
 316                 throw new UnexpectedValueException( __METHOD__ . ": got serializer '$serializer'." );
 317         }
 318
 319         protected function unserialize( $value ) {
 320                 if ( $this->isInteger( $value ) ) {
 321                         return (int)$value;
 322                 }
 323
 324                 $serializer = $this->client->getOption( Memcached::OPT_SERIALIZER );
 325                 if ( $serializer === Memcached::SERIALIZER_PHP ) {
 326                         return unserialize( $value );
 327                 } elseif ( $serializer === Memcached::SERIALIZER_IGBINARY ) {
 328                         return igbinary_unserialize( $value );
 329                 }
 330
 331                 throw new UnexpectedValueException( __METHOD__ . ": got serializer '$serializer'." );
 332         }
 333 }