sync the repo
[hiphop-php.git] / hphp / runtime / ext / memcached / ext_memcached.php
blobb7123670fab1b4856ae74834a473a2232785e6f5
1 <?hh
3 /**
4 * Represents a connection to a set of memcached servers.
5 */
6 <<__NativeData>>
7 class Memcached {
8 // Signifies we have provide a session handler
9 const HAVE_SESSION = false;
10 /**
11 * Create a Memcached instance
13 * @param string $persistent_id - By default the Memcached instances are
14 * destroyed at the end of the request. To create an instance that persists
15 * between requests, use persistent_id to specify a unique ID for the
16 * instance. All instances created with the same persistent_id will share the
17 * same connection.
19 <<__Native>>
20 public function __construct(?string $persistent_id = null): void;
22 /**
23 * Add an item under a new key
25 * @param string $key -
26 * @param mixed $value -
27 * @param int $expiration -
29 * @return bool - The Memcached::getResultCode will return
30 * Memcached::RES_NOTSTORED if the key already exists.
32 public function add(mixed $key,
33 mixed $value,
34 int $expiration = 0): bool {
35 return $this->addByKey('', $key, $value, $expiration);
38 /**
39 * Add an item under a new key on a specific server
41 * @param string $server_key -
42 * @param string $key -
43 * @param mixed $value -
44 * @param int $expiration -
46 * @return bool - The Memcached::getResultCode will return
47 * Memcached::RES_NOTSTORED if the key already exists.
49 <<__Native>>
50 public function addByKey(string $server_key,
51 string $key,
52 mixed $value,
53 int $expiration = 0): bool;
55 /**
56 * Add a server to the server pool
58 * @param string $host - The hostname of the memcache server. If the
59 * hostname is invalid, data-related operations will set
60 * Memcached::RES_HOST_LOOKUP_FAILURE result code.
61 * @param int $port - The port on which memcache is running. Usually,
62 * this is 11211.
63 * @param int $weight - The weight of the server relative to the total
64 * weight of all the servers in the pool. This controls the probability
65 * of the server being selected for operations. This is used only with
66 * consistent distribution option and usually corresponds to the amount
67 * of memory available to memcache on that server.
69 * @return bool -
71 <<__Native>>
72 public function addServer(string $host,
73 int $port,
74 int $weight = 0): bool;
76 /**
77 * Add multiple servers to the server pool
79 * @param array $servers -
81 * @return bool -
83 public function addServers(
84 varray_or_darray<varray_or_darray<mixed>> $servers,
85 ): bool {
86 $servers_vals = array_values($servers);
87 foreach($servers_vals as $i => $server) {
88 $server = array_values($server);
89 if (!\HH\is_any_array($server)) {
90 trigger_error(
91 sprintf('Server list entry #%d is not an array', $i + 1),
92 E_WARNING
94 continue;
96 if (count($server) < 1) {
97 trigger_error(
98 sprintf('Could not get server host for entry #%d', $i + 1),
99 E_WARNING
101 continue;
103 if (count($server) < 2) {
104 trigger_error(
105 sprintf('Could not get server port for entry #%d', $i + 1),
106 E_WARNING
108 continue;
111 $host = (string)$server[0];
112 $port = (int)$server[1];
113 if (count($server) < 3) {
114 $weight = 0;
115 } else {
116 $weight = (int)$server[2];
119 if (!$this->addServer($host, $port, $weight)) {
120 trigger_error(
121 sprintf('Could not add entry #%d to the server list', $i + 1),
122 E_WARNING
126 return true;
130 * Append data to an existing item
132 * @param string $key -
133 * @param string $value - The string to append.
135 * @return bool - The Memcached::getResultCode will return
136 * Memcached::RES_NOTSTORED if the key does not exist.
138 public function append(mixed $key,
139 mixed $value): bool {
140 return $this->appendByKey('', $key, $value);
144 * Append data to an existing item on a specific server
146 * @param string $server_key -
147 * @param string $key -
148 * @param string $value - The string to append.
150 * @return bool - The Memcached::getResultCode will return
151 * Memcached::RES_NOTSTORED if the key does not exist.
153 <<__Native>>
154 public function appendByKey(string $server_key,
155 string $key,
156 string $value): bool;
159 * Compare and swap an item
161 * @param float $cas_token - Unique value associated with the existing
162 * item. Generated by memcache.
163 * @param string $key -
164 * @param mixed $value -
165 * @param int $expiration -
167 * @return bool - The Memcached::getResultCode will return
168 * Memcached::RES_DATA_EXISTS if the item you are trying to store has
169 * been modified since you last fetched it.
171 public function cas(float $cas_token,
172 string $key,
173 mixed $value,
174 int $expiration = 0): bool {
175 return $this->casByKey($cas_token, '', $key, $value, $expiration);
179 * Compare and swap an item on a specific server
181 * @param float $cas_token - Unique value associated with the existing
182 * item. Generated by memcache.
183 * @param string $server_key -
184 * @param string $key -
185 * @param mixed $value -
186 * @param int $expiration -
188 * @return bool - The Memcached::getResultCode will return
189 * Memcached::RES_DATA_EXISTS if the item you are trying to store has
190 * been modified since you last fetched it.
192 <<__Native>>
193 public function casByKey(float $cas_token,
194 string $server_key,
195 string $key,
196 mixed $value,
197 int $expiration = 0): bool;
200 * Decrement numeric item's value
202 * @param string $key - The key of the item to decrement.
203 * @param int $offset - The amount by which to decrement the item's
204 * value.
205 * @param mixed $initial_value - The value to set the item to if it
206 * doesn't currently exist. False to fail if the key does not exist
207 * @param int $expiry - The expiry time to set on the item.
209 * @return mixed - Returns item's new value on success. False if the key
210 * doesn't exist and no initial_value was provided.
212 <<__Native>>
213 public function decrement(string $key,
214 int $offset = 1,
215 mixed $initial_value = false,
216 int $expiry = 0): mixed;
219 * Decrement numeric item's value, stored on a specific server
221 * @param string $server_key -
222 * @param string $key - The key of the item to decrement.
223 * @param int $offset - The amount by which to decrement the item's
224 * value.
225 * @param int $initial_value - The value to set the item to if it
226 * doesn't currently exist. False to fail if the key does not exist.
227 * @param int $expiry - The expiry time to set on the item.
229 * @return int - Returns item's new value on success. False if the key
230 * doesn't exist and no initial_value was provided.
232 <<__Native>>
233 public function decrementByKey(string $server_key,
234 string $key,
235 int $offset = 1,
236 mixed $initial_value = false,
237 int $expiry = 0): mixed;
240 * Delete an item
242 * @param string $key - The key to be deleted.
243 * @param int $time - The amount of time the server will wait to delete
244 * the item.
246 * @return bool - The Memcached::getResultCode will return
247 * Memcached::RES_NOTFOUND if the key does not exist.
249 public function delete(mixed $key,
250 int $time = 0): bool {
251 return $this->deleteByKey('', $key, $time);
255 * Add an item under a new key on a specific server
257 * @param string $server_key - The key identifying the server to store the value on
258 * or retrieve it from. Instead of hashing on the actual key for the item, we
259 * hash on the server key when deciding which memcached server to talk to.
260 * This allows related items to be grouped together on a single server for
261 * efficiency with multi operations..
262 * @param array $keys - The keys to be deleted.
263 * @param int $time - The amount of time the server will wait to delete
264 * the items.
266 * @return array
268 <<__Native>>
269 public function deleteMultiByKey(string $server_key, varray $keys,
270 int $time = 0): mixed;
273 * Add an item under a new key on a specific server
275 * @param array $keys - The keys to be deleted.
276 * @param int $time - The amount of time the server will wait to delete
277 * the items.
279 * @return array
281 public function deleteMulti(varray $keys, int $time = 0): mixed {
282 return $this->deleteMultiByKey('', $keys, $time);
286 * Delete an item from a specific server
288 * @param string $server_key -
289 * @param string $key - The key to be deleted.
290 * @param int $time - The amount of time the server will wait to delete
291 * the item.
293 * @return bool - The Memcached::getResultCode will return
294 * Memcached::RES_NOTFOUND if the key does not exist.
296 <<__Native>>
297 public function deleteByKey(string $server_key,
298 string $key,
299 int $time = 0): bool;
302 * Fetch the next result
304 * @return array - Returns the next result or FALSE otherwise. The
305 * Memcached::getResultCode will return Memcached::RES_END if result
306 * set is exhausted.
308 <<__Native>>
309 public function fetch(): mixed;
312 * Fetch all the remaining results
314 * @return array - Returns the results.
316 <<__Native>>
317 public function fetchAll(): mixed;
320 * Invalidate all items in the cache
322 * @param int $delay - Numer of seconds to wait before invalidating the
323 * items.
325 * @return bool -
327 <<__Native>>
328 public function flush(int $delay = 0): bool;
331 * Retrieve an item
333 * @param string $key - The key of the item to retrieve.
334 * @param callable $cache_cb - Read-through caching callback or NULL.
335 * @param float $cas_token - The variable to store the CAS token in.
337 * @return mixed - Returns the value stored in the cache or FALSE
338 * otherwise. The Memcached::getResultCode will return
339 * Memcached::RES_NOTFOUND if the key does not exist.
341 public function get(mixed $key,
342 mixed $cache_cb = null): mixed {
343 return $this->getByKey('', $key, $cache_cb);
346 public function getWithCasToken(mixed $key,
347 ?mixed $cache_cb,
348 inout mixed $cas_token): mixed {
349 $result = $this->getByKeyWithCasToken(
351 $key,
352 $cache_cb,
353 inout $cas_token,
355 return $result;
358 /* Memcached::getAllKeys() Gets the keys stored on all the servers
359 * @return mixed - Returns the keys stored on all the servers on success or
360 * FALSE on failure.
362 <<__Native>>
363 public function getAllKeys(): mixed;
366 * Retrieve an item from a specific server
368 * @param string $server_key -
369 * @param string $key - The key of the item to fetch.
370 * @param mixed $cache_cb - Read-through caching callback or NULL
371 * @param float $cas_token - The variable to store the CAS token in.
373 * @return mixed - Returns the value stored in the cache or FALSE
374 * otherwise. The Memcached::getResultCode will return
375 * Memcached::RES_NOTFOUND if the key does not exist.
377 <<__Native>>
378 public function getByKey(string $server_key,
379 string $key,
380 mixed $cache_cb = null): mixed;
382 <<__Native>>
383 public function getByKeyWithCasToken(string $server_key,
384 string $key,
385 mixed $cache_cb,
386 <<__OutOnly>>
387 inout mixed $cas_token): mixed;
390 * Request multiple items
392 * @param array $keys - Array of keys to request.
393 * @param bool $with_cas - Whether to request CAS token values also.
394 * @param callable $value_cb - The result callback or NULL.
396 * @return bool -
398 public function getDelayed(mixed $keys,
399 mixed $with_cas = false,
400 mixed $value_cb = null): bool {
401 return $this->getDelayedByKey('', $keys, $with_cas, $value_cb);
405 * Request multiple items from a specific server
407 * @param string $server_key -
408 * @param array $keys - Array of keys to request.
409 * @param bool $with_cas - Whether to request CAS token values also.
410 * @param callable $value_cb - The result callback or NULL.
412 * @return bool -
414 <<__Native>>
415 public function getDelayedByKey(string $server_key,
416 varray $keys,
417 bool $with_cas = false,
418 ?callable $value_cb = null): bool;
421 * Retrieve multiple items
423 * @param array $keys - Array of keys to retrieve.
424 * @param array $cas_tokens - The variable to store the CAS tokens for
425 * the found items.
426 * @param int $flags - The flags for the get operation.
428 * @return mixed - Returns the array of found items.
430 public function getMulti(mixed $keys,
431 int $flags = 0): mixed {
432 return $this->getMultiByKey('', $keys, $flags);
435 public function getMultiWithCasTokens(
436 mixed $keys,
437 inout mixed $cas_tokens,
438 int $flags = 0,
439 ): mixed {
440 $result = $this->getMultiByKeyWithCasTokens(
442 $keys,
443 inout $cas_tokens,
444 $flags,
446 return $result;
450 * Retrieve multiple items from a specific server
452 * @param string $server_key -
453 * @param array $keys - Array of keys to retrieve.
454 * @param string $cas_tokens - The variable to store the CAS tokens for
455 * the found items.
456 * @param int $flags - The flags for the get operation.
458 * @return array - Returns the array of found items.
460 <<__Native>>
461 public function getMultiByKey(string $server_key,
462 varray $keys,
463 int $flags = 0): mixed;
465 <<__Native>>
466 public function getMultiByKeyWithCasTokens(string $server_key,
467 varray $keys,
468 <<__OutOnly>>
469 inout mixed $cas_tokens,
470 int $flags = 0): mixed;
473 * Retrieve a Memcached option value
475 * @param int $option - One of the Memcached::OPT_* constants.
477 * @return mixed - Returns the value of the requested option, or FALSE
478 * on error.
480 <<__Native>>
481 public function getOption(int $option): mixed;
484 * Return the result code of the last operation
486 * @return int - Result code of the last Memcached operation.
488 <<__Native>>
489 public function getResultCode(): int;
492 * Return the message describing the result of the last operation
494 * @return string - Message describing the result of the last Memcached
495 * operation.
497 <<__Native>>
498 public function getResultMessage(): string;
501 * Map a key to a server
503 * @param string $server_key -
505 * @return array - Returns an array containing three keys of host,
506 * port, and weight on success or FALSE on failure.
508 <<__Native>>
509 public function getServerByKey(string $server_key): mixed;
512 * Get the list of the servers in the pool
514 * @return array - The list of all servers in the server pool.
516 <<__Native>>
517 public function getServerList(): varray;
520 * Clears all server from the list
522 * @return bool - Returns TRUE on success or FALSE on failure.
524 <<__Native>>
525 public function resetServerList(): bool;
528 * Get server pool statistics
530 * @return array - Array of server statistics, one entry per server.
532 <<__Native>>
533 public function getStats(): mixed;
536 * Get server pool version info
538 * @return array - Array of server versions, one entry per server.
540 <<__Native>>
541 public function getVersion(): mixed;
544 * Increment numeric item's value
546 * @param string $key - The key of the item to increment.
547 * @param int $offset - The amount by which to increment the item's
548 * value.
549 * @param mixed $initial_value - The value to set the item to if it
550 * doesn't currently exist. False to fail if the key does not exist.
551 * @param int $expiry - The expiry time to set on the item.
553 * @return mixed - Returns new item's value on success. False if the key
554 * doesn't exist.
556 <<__Native>>
557 public function increment(string $key,
558 int $offset = 1,
559 mixed $initial_value = false,
560 int $expiry = 0): mixed;
563 * Increment numeric item's value, stored on a specific server
565 * @param string $server_key -
566 * @param string $key - The key of the item to increment.
567 * @param int $offset - The amount by which to increment the item's
568 * value.
569 * @param mixed $initial_value - The value to set the item to if it
570 * doesn't currently exist. False to fail if the key does not exist.
571 * @param int $expiry - The expiry time to set on the item.
573 * @return mixed - Returns new item's value on success. False if the key
574 * doesn't exist and no initial_value was provided.
576 <<__Native>>
577 public function incrementByKey(string $server_key,
578 string $key,
579 int $offset = 1,
580 mixed $initial_value = false,
581 int $expiry = 0): mixed;
584 * Check if a persitent connection to memcache is being used.
586 * @return bool - Returns true if Memcache instance uses a persistent
587 * connection, false otherwise.
589 <<__Native>>
590 public function isPersistent(): bool;
593 * Check if the instance was recently created
595 * @return bool - Returns the true if instance is recently created,
596 * false otherwise.
598 <<__Native>>
599 public function isPristine(): bool;
602 * Prepend data to an existing item
604 * @param string $key - The key of the item to prepend the data to.
605 * @param string $value - The string to prepend.
607 * @return bool - The Memcached::getResultCode will return
608 * Memcached::RES_NOTSTORED if the key does not exist.
610 public function prepend(mixed $key,
611 mixed $value): bool {
612 return $this->prependByKey('', $key, $value);
616 * Prepend data to an existing item on a specific server
618 * @param string $server_key -
619 * @param string $key - The key of the item to prepend the data to.
620 * @param string $value - The string to prepend.
622 * @return bool - The Memcached::getResultCode will return
623 * Memcached::RES_NOTSTORED if the key does not exist.
625 <<__Native>>
626 public function prependByKey(string $server_key,
627 string $key,
628 string $value): bool;
631 * Memcached::quit() closes any open connections to the memcache servers.
632 * @return bool TRUE on success or FALSE on failure
634 <<__Native>>
635 public function quit(): bool;
638 * Replace the item under an existing key
640 * @param string $key -
641 * @param mixed $value -
642 * @param int $expiration -
644 * @return bool - The Memcached::getResultCode will return
645 * Memcached::RES_NOTSTORED if the key does not exist.
647 public function replace(mixed $key,
648 mixed $value,
649 int $expiration = 0): bool {
650 return $this->replaceByKey('', $key, $value, $expiration);
654 * Replace the item under an existing key on a specific server
656 * @param string $server_key -
657 * @param string $key -
658 * @param mixed $value -
659 * @param int $expiration -
661 * @return bool - The Memcached::getResultCode will return
662 * Memcached::RES_NOTSTORED if the key does not exist.
664 <<__Native>>
665 public function replaceByKey(string $server_key,
666 string $key,
667 mixed $value,
668 int $expiration = 0): bool;
671 * Store an item
673 * @param string $key -
674 * @param mixed $value -
675 * @param int $expiration -
677 * @return bool -
679 public function set(mixed $key,
680 mixed $value,
681 int $expiration = 0): bool {
682 return $this->setByKey('', $key, $value, $expiration);
686 * Store an item on a specific server
688 * @param string $server_key -
689 * @param string $key -
690 * @param mixed $value -
691 * @param int $expiration -
693 * @return bool -
695 <<__Native>>
696 public function setByKey(string $server_key,
697 string $key,
698 mixed $value,
699 int $expiration = 0): bool;
702 * Store multiple items
704 * @param array $items -
705 * @param int $expiration -
707 * @return bool -
709 public function setMulti(darray<string, mixed> $items,
710 int $expiration = 0): bool {
711 return $this->setMultiByKey('', $items, $expiration);
715 * Store multiple items on a specific server
717 * @param string $server_key -
718 * @param array $items -
719 * @param int $expiration -
721 * @return bool -
723 public function setMultiByKey(string $server_key,
724 darray<string, mixed> $items,
725 int $expiration = 0): bool {
726 foreach($items as $key => $value) {
727 if (is_int($key)) {
728 // numeric strings (e.g. '5') become integers as array keys
729 $key = (string)$key;
730 } else if (!is_string($key)) {
731 continue;
733 if (!$this->setByKey($server_key, $key, $value, $expiration)) {
734 return false;
737 return true;
741 * Set a Memcached option
743 * @param int $option -
744 * @param mixed $value -
746 * @return bool -
748 <<__Native>>
749 public function setOption(int $option,
750 mixed $value): bool;
753 * Set Memcached options
755 * @param array $options -
757 * @return bool -
759 public function setOptions(darray<int, mixed> $options): bool {
760 foreach($options as $option => $value) {
761 if (!$this->setOption($option, $value)) {
762 return false;
765 return true;
769 * Set a new expiration on an item
771 * @param string $key - The key under which to store the value.
772 * @param int $expiration - The expiration time, defaults to 0.
774 * @return bool - Returns TRUE on success or FALSE on failure.
776 public function touch(string $key,
777 int $expiration = 0): bool {
778 return $this->touchByKey('', $key, $expiration);
782 * Set a new expiration on an item on a specific server
784 * @param string $server_key - The key identifying the server to store the
785 * value on or retrieve it from. Instead of hashing on the actual key for
786 * the item, we hash on the server key when deciding which memcached server
787 * to talk to. This allows related items to be grouped together on a single
788 * server for efficiency with multi operations.
789 * @param string $key - The key under which to store the value.
790 * @param int $expiration - The expiration time, defaults to 0.
792 * @return bool - Returns TRUE on success or FALSE on failure.
794 <<__Native>>
795 public function touchByKey(string $server_key,
796 string $key,
797 int $expiration = 0): bool;
801 class MemcachedException {