3 * Object caching using memcached.
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.
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.
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
25 * A wrapper class for the PECL memcached client
29 class MemcachedPeclBagOStuff
extends MemcachedBagOStuff
{
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
49 function __construct( $params ) {
50 parent
::__construct( $params );
52 // Default class-specific parameters
54 'compress_threshold' => 1500,
55 'connect_timeout' => 0.5,
56 'serializer' => 'php',
57 'use_binary_protocol' => false,
58 'allow_tcp_nagle_delay' => true
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 );
69 $client = new Memcached
;
70 $this->initializeClient( $client, $params );
73 $this->client
= $client;
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'] );
82 * Initialize the client only if needed and reuse it otherwise.
83 * This avoids duplicate servers in the list and new connections.
85 * @param Memcached $client
86 * @param array $params
87 * @throws RuntimeException
89 private function initializeClient( Memcached
$client, array $params ) {
90 if ( $client->getServerList() ) {
91 $this->logger
->debug( __METHOD__
. ": pre-initialized client instance." );
93 return; // preserve persistent handle
96 $this->logger
->debug( __METHOD__
. ": initializing new client instance." );
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
111 if ( isset( $params['retry_timeout'] ) ) {
112 $options[Memcached
::OPT_RETRY_TIMEOUT
] = $params['retry_timeout'];
114 if ( isset( $params['server_failure_limit'] ) ) {
115 $options[Memcached
::OPT_SERVER_FAILURE_LIMIT
] = $params['server_failure_limit'];
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.'
126 $options[Memcached
::OPT_SERIALIZER
] = Memcached
::SERIALIZER_IGBINARY
;
129 if ( !$client->setOptions( $options ) ) {
130 throw new RuntimeException(
131 "Invalid options: " . json_encode( $options, JSON_PRETTY_PRINT
)
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)
142 $servers[] = [ $host, false ]; // (ip or path, port)
146 if ( !$client->addServers( $servers ) ) {
147 throw new RuntimeException( "Failed to inject server address list" );
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'];
165 $result = $this->client
->get( $this->validateKeyEncoding( $key ), null, $casToken );
167 $result = $this->checkResult( $key, $result );
171 protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
172 $this->debug( "set($key)" );
173 $result = $this->client
->set(
174 $this->validateKeyEncoding( $key ),
176 $this->fixExpiry( $exptime )
178 if ( $result === false && $this->client
->getResultCode() === Memcached
::RES_NOTSTORED
) {
179 // "Not stored" is always used as the mcrouter response with AllAsyncRoute
182 return $this->checkResult( $key, $result );
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 );
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
199 return $this->checkResult( $key, $result );
202 public function add( $key, $value, $exptime = 0, $flags = 0 ) {
203 $this->debug( "add($key)" );
204 $result = $this->client
->add(
205 $this->validateKeyEncoding( $key ),
207 $this->fixExpiry( $exptime )
209 return $this->checkResult( $key, $result );
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 );
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 );
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
231 * @param string $key The key used by the caller, or false if there wasn't one.
232 * @param mixed $result The return value
235 protected function checkResult( $key, $result ) {
236 if ( $result !== false ) {
239 switch ( $this->client
->getResultCode() ) {
240 case Memcached
::RES_SUCCESS
:
242 case Memcached
::RES_DATA_EXISTS
:
243 case Memcached
::RES_NOTSTORED
:
244 case Memcached
::RES_NOTFOUND
:
245 $this->debug( "result: " . $this->client
->getResultMessage() );
248 $msg = $this->client
->getResultMessage();
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";
256 $msg = "Memcached error: $msg";
258 $this->logger
->error( $msg, $logCtx );
259 $this->setLastError( BagOStuff
::ERR_UNEXPECTED
);
264 public function doGetMulti( array $keys, $flags = 0 ) {
265 $this->debug( 'getMulti(' . implode( ', ', $keys ) . ')' );
266 foreach ( $keys as $key ) {
267 $this->validateKeyEncoding( $key );
269 $result = $this->client
->getMulti( $keys ) ?
: [];
270 return $this->checkResult( false, $result );
273 public 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 );
278 $result = $this->client
->setMulti( $data, $this->fixExpiry( $exptime ) );
279 return $this->checkResult( false, $result );
282 public function doDeleteMulti( array $keys, $flags = 0 ) {
283 $this->debug( 'deleteMulti(' . implode( ', ', $keys ) . ')' );
284 foreach ( $keys as $key ) {
285 $this->validateKeyEncoding( $key );
287 $result = $this->client
->deleteMulti( $keys ) ?
: [];
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
295 return $this->checkResult( false, $ok );
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 );
304 protected function serialize( $value ) {
305 if ( is_int( $value ) ) {
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 );
316 throw new UnexpectedValueException( __METHOD__
. ": got serializer '$serializer'." );
319 protected function unserialize( $value ) {
320 if ( $this->isInteger( $value ) ) {
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 );
331 throw new UnexpectedValueException( __METHOD__
. ": got serializer '$serializer'." );