PageRenderTime 64ms CodeModel.GetById 10ms RepoModel.GetById 0ms app.codeStats 0ms

/hphp/runtime/ext/memcached/ext_memcached.php

http://github.com/facebook/hiphop-php
PHP | 800 lines | 278 code | 58 blank | 464 comment | 9 complexity | 6aaa63af62ef298d50310a8ffa50de4c MD5 | raw file
Possible License(s): LGPL-2.1, BSD-2-Clause, BSD-3-Clause, MPL-2.0-no-copyleft-exception, MIT, LGPL-2.0, Apache-2.0
  1. <?hh // partial
  2. /**
  3. * Represents a connection to a set of memcached servers.
  4. */
  5. <<__NativeData("MemcachedData")>>
  6. class Memcached {
  7. // Signifies we have provide a session handler
  8. const HAVE_SESSION = false;
  9. /**
  10. * Create a Memcached instance
  11. *
  12. * @param string $persistent_id - By default the Memcached instances are
  13. * destroyed at the end of the request. To create an instance that persists
  14. * between requests, use persistent_id to specify a unique ID for the
  15. * instance. All instances created with the same persistent_id will share the
  16. * same connection.
  17. */
  18. <<__Native>>
  19. public function __construct(?string $persistent_id = null): void;
  20. /**
  21. * Add an item under a new key
  22. *
  23. * @param string $key -
  24. * @param mixed $value -
  25. * @param int $expiration -
  26. *
  27. * @return bool - The Memcached::getResultCode will return
  28. * Memcached::RES_NOTSTORED if the key already exists.
  29. */
  30. public function add(mixed $key,
  31. mixed $value,
  32. int $expiration = 0): bool {
  33. return $this->addByKey('', $key, $value, $expiration);
  34. }
  35. /**
  36. * Add an item under a new key on a specific server
  37. *
  38. * @param string $server_key -
  39. * @param string $key -
  40. * @param mixed $value -
  41. * @param int $expiration -
  42. *
  43. * @return bool - The Memcached::getResultCode will return
  44. * Memcached::RES_NOTSTORED if the key already exists.
  45. */
  46. <<__Native>>
  47. public function addByKey(string $server_key,
  48. string $key,
  49. mixed $value,
  50. int $expiration = 0): bool;
  51. /**
  52. * Add a server to the server pool
  53. *
  54. * @param string $host - The hostname of the memcache server. If the
  55. * hostname is invalid, data-related operations will set
  56. * Memcached::RES_HOST_LOOKUP_FAILURE result code.
  57. * @param int $port - The port on which memcache is running. Usually,
  58. * this is 11211.
  59. * @param int $weight - The weight of the server relative to the total
  60. * weight of all the servers in the pool. This controls the probability
  61. * of the server being selected for operations. This is used only with
  62. * consistent distribution option and usually corresponds to the amount
  63. * of memory available to memcache on that server.
  64. *
  65. * @return bool -
  66. */
  67. <<__Native>>
  68. public function addServer(string $host,
  69. int $port,
  70. int $weight = 0): bool;
  71. /**
  72. * Add multiple servers to the server pool
  73. *
  74. * @param array $servers -
  75. *
  76. * @return bool -
  77. */
  78. public function addServers(array<array<mixed>> $servers): bool {
  79. $servers_vals = array_values($servers);
  80. foreach($servers_vals as $i => $server) {
  81. $server = array_values($server);
  82. if (!is_array($server)) {
  83. trigger_error(
  84. sprintf('Server list entry #%d is not an array', $i + 1),
  85. E_WARNING
  86. );
  87. continue;
  88. }
  89. if (count($server) < 1) {
  90. trigger_error(
  91. sprintf('Could not get server host for entry #%d', $i + 1),
  92. E_WARNING
  93. );
  94. continue;
  95. }
  96. if (count($server) < 2) {
  97. trigger_error(
  98. sprintf('Could not get server port for entry #%d', $i + 1),
  99. E_WARNING
  100. );
  101. continue;
  102. }
  103. $host = (string)$server[0];
  104. $port = (int)$server[1];
  105. if (count($server) < 3) {
  106. $weight = 0;
  107. } else {
  108. $weight = (int)$server[2];
  109. }
  110. if (!$this->addServer($host, $port, $weight)) {
  111. trigger_error(
  112. sprintf('Could not add entry #%d to the server list', $i + 1),
  113. E_WARNING
  114. );
  115. }
  116. }
  117. return true;
  118. }
  119. /**
  120. * Append data to an existing item
  121. *
  122. * @param string $key -
  123. * @param string $value - The string to append.
  124. *
  125. * @return bool - The Memcached::getResultCode will return
  126. * Memcached::RES_NOTSTORED if the key does not exist.
  127. */
  128. public function append(mixed $key,
  129. mixed $value): bool {
  130. return $this->appendByKey('', $key, $value);
  131. }
  132. /**
  133. * Append data to an existing item on a specific server
  134. *
  135. * @param string $server_key -
  136. * @param string $key -
  137. * @param string $value - The string to append.
  138. *
  139. * @return bool - The Memcached::getResultCode will return
  140. * Memcached::RES_NOTSTORED if the key does not exist.
  141. */
  142. <<__Native>>
  143. public function appendByKey(string $server_key,
  144. string $key,
  145. string $value): bool;
  146. /**
  147. * Compare and swap an item
  148. *
  149. * @param float $cas_token - Unique value associated with the existing
  150. * item. Generated by memcache.
  151. * @param string $key -
  152. * @param mixed $value -
  153. * @param int $expiration -
  154. *
  155. * @return bool - The Memcached::getResultCode will return
  156. * Memcached::RES_DATA_EXISTS if the item you are trying to store has
  157. * been modified since you last fetched it.
  158. */
  159. public function cas(float $cas_token,
  160. string $key,
  161. mixed $value,
  162. int $expiration = 0): bool {
  163. return $this->casByKey($cas_token, '', $key, $value, $expiration);
  164. }
  165. /**
  166. * Compare and swap an item on a specific server
  167. *
  168. * @param float $cas_token - Unique value associated with the existing
  169. * item. Generated by memcache.
  170. * @param string $server_key -
  171. * @param string $key -
  172. * @param mixed $value -
  173. * @param int $expiration -
  174. *
  175. * @return bool - The Memcached::getResultCode will return
  176. * Memcached::RES_DATA_EXISTS if the item you are trying to store has
  177. * been modified since you last fetched it.
  178. */
  179. <<__Native>>
  180. public function casByKey(float $cas_token,
  181. string $server_key,
  182. string $key,
  183. mixed $value,
  184. int $expiration = 0): bool;
  185. /**
  186. * Decrement numeric item's value
  187. *
  188. * @param string $key - The key of the item to decrement.
  189. * @param int $offset - The amount by which to decrement the item's
  190. * value.
  191. * @param mixed $initial_value - The value to set the item to if it
  192. * doesn't currently exist. False to fail if the key does not exist
  193. * @param int $expiry - The expiry time to set on the item.
  194. *
  195. * @return mixed - Returns item's new value on success. False if the key
  196. * doesn't exist and no initial_value was provided.
  197. */
  198. <<__Native>>
  199. public function decrement(string $key,
  200. int $offset = 1,
  201. mixed $initial_value = false,
  202. int $expiry = 0): mixed;
  203. /**
  204. * Decrement numeric item's value, stored on a specific server
  205. *
  206. * @param string $server_key -
  207. * @param string $key - The key of the item to decrement.
  208. * @param int $offset - The amount by which to decrement the item's
  209. * value.
  210. * @param int $initial_value - The value to set the item to if it
  211. * doesn't currently exist. False to fail if the key does not exist.
  212. * @param int $expiry - The expiry time to set on the item.
  213. *
  214. * @return int - Returns item's new value on success. False if the key
  215. * doesn't exist and no initial_value was provided.
  216. */
  217. <<__Native>>
  218. public function decrementByKey(string $server_key,
  219. string $key,
  220. int $offset = 1,
  221. mixed $initial_value = false,
  222. int $expiry = 0): mixed;
  223. /**
  224. * Delete an item
  225. *
  226. * @param string $key - The key to be deleted.
  227. * @param int $time - The amount of time the server will wait to delete
  228. * the item.
  229. *
  230. * @return bool - The Memcached::getResultCode will return
  231. * Memcached::RES_NOTFOUND if the key does not exist.
  232. */
  233. public function delete(mixed $key,
  234. int $time = 0): bool {
  235. return $this->deleteByKey('', $key, $time);
  236. }
  237. /**
  238. * Add an item under a new key on a specific server
  239. *
  240. * @param string $server_key - The key identifying the server to store the value on
  241. * or retrieve it from. Instead of hashing on the actual key for the item, we
  242. * hash on the server key when deciding which memcached server to talk to.
  243. * This allows related items to be grouped together on a single server for
  244. * efficiency with multi operations..
  245. * @param array $keys - The keys to be deleted.
  246. * @param int $time - The amount of time the server will wait to delete
  247. * the items.
  248. *
  249. * @return array
  250. */
  251. <<__Native>>
  252. public function deleteMultiByKey(string $server_key, array $keys,
  253. int $time = 0): mixed;
  254. /**
  255. * Add an item under a new key on a specific server
  256. *
  257. * @param array $keys - The keys to be deleted.
  258. * @param int $time - The amount of time the server will wait to delete
  259. * the items.
  260. *
  261. * @return array
  262. */
  263. public function deleteMulti(array $keys, int $time = 0): mixed {
  264. return $this->deleteMultiByKey('', $keys, $time);
  265. }
  266. /**
  267. * Delete an item from a specific server
  268. *
  269. * @param string $server_key -
  270. * @param string $key - The key to be deleted.
  271. * @param int $time - The amount of time the server will wait to delete
  272. * the item.
  273. *
  274. * @return bool - The Memcached::getResultCode will return
  275. * Memcached::RES_NOTFOUND if the key does not exist.
  276. */
  277. <<__Native>>
  278. public function deleteByKey(string $server_key,
  279. string $key,
  280. int $time = 0): bool;
  281. /**
  282. * Fetch the next result
  283. *
  284. * @return array - Returns the next result or FALSE otherwise. The
  285. * Memcached::getResultCode will return Memcached::RES_END if result
  286. * set is exhausted.
  287. */
  288. <<__Native>>
  289. public function fetch(): mixed;
  290. /**
  291. * Fetch all the remaining results
  292. *
  293. * @return array - Returns the results.
  294. */
  295. <<__Native>>
  296. public function fetchAll(): mixed;
  297. /**
  298. * Invalidate all items in the cache
  299. *
  300. * @param int $delay - Numer of seconds to wait before invalidating the
  301. * items.
  302. *
  303. * @return bool -
  304. */
  305. <<__Native>>
  306. public function flush(int $delay = 0): bool;
  307. /**
  308. * Retrieve an item
  309. *
  310. * @param string $key - The key of the item to retrieve.
  311. * @param callable $cache_cb - Read-through caching callback or NULL.
  312. * @param float $cas_token - The variable to store the CAS token in.
  313. *
  314. * @return mixed - Returns the value stored in the cache or FALSE
  315. * otherwise. The Memcached::getResultCode will return
  316. * Memcached::RES_NOTFOUND if the key does not exist.
  317. */
  318. public function get(mixed $key,
  319. ?mixed $cache_cb = null): mixed {
  320. return $this->getByKey('', $key, $cache_cb);
  321. }
  322. public function getWithCasToken(mixed $key,
  323. ?mixed $cache_cb,
  324. inout mixed $cas_token): mixed {
  325. $result = $this->getByKeyWithCasToken(
  326. '',
  327. $key,
  328. $cache_cb,
  329. inout $cas_token,
  330. );
  331. return $result;
  332. }
  333. /* Memcached::getAllKeys() Gets the keys stored on all the servers
  334. * @return mixed - Returns the keys stored on all the servers on success or
  335. * FALSE on failure.
  336. */
  337. <<__Native>>
  338. public function getAllKeys(): mixed;
  339. /**
  340. * Retrieve an item from a specific server
  341. *
  342. * @param string $server_key -
  343. * @param string $key - The key of the item to fetch.
  344. * @param mixed $cache_cb - Read-through caching callback or NULL
  345. * @param float $cas_token - The variable to store the CAS token in.
  346. *
  347. * @return mixed - Returns the value stored in the cache or FALSE
  348. * otherwise. The Memcached::getResultCode will return
  349. * Memcached::RES_NOTFOUND if the key does not exist.
  350. */
  351. <<__Native>>
  352. public function getByKey(string $server_key,
  353. string $key,
  354. mixed $cache_cb = null): mixed;
  355. <<__Native>>
  356. public function getByKeyWithCasToken(string $server_key,
  357. string $key,
  358. mixed $cache_cb,
  359. <<__OutOnly>>
  360. inout mixed $cas_token): mixed;
  361. /**
  362. * Request multiple items
  363. *
  364. * @param array $keys - Array of keys to request.
  365. * @param bool $with_cas - Whether to request CAS token values also.
  366. * @param callable $value_cb - The result callback or NULL.
  367. *
  368. * @return bool -
  369. */
  370. public function getDelayed(mixed $keys,
  371. mixed $with_cas = false,
  372. mixed $value_cb = null): bool {
  373. return $this->getDelayedByKey('', $keys, $with_cas, $value_cb);
  374. }
  375. /**
  376. * Request multiple items from a specific server
  377. *
  378. * @param string $server_key -
  379. * @param array $keys - Array of keys to request.
  380. * @param bool $with_cas - Whether to request CAS token values also.
  381. * @param callable $value_cb - The result callback or NULL.
  382. *
  383. * @return bool -
  384. */
  385. <<__Native>>
  386. public function getDelayedByKey(string $server_key,
  387. array $keys,
  388. bool $with_cas = false,
  389. ?callable $value_cb = null): bool;
  390. /**
  391. * Retrieve multiple items
  392. *
  393. * @param array $keys - Array of keys to retrieve.
  394. * @param array $cas_tokens - The variable to store the CAS tokens for
  395. * the found items.
  396. * @param int $flags - The flags for the get operation.
  397. *
  398. * @return mixed - Returns the array of found items.
  399. */
  400. public function getMulti(mixed $keys,
  401. int $flags = 0): mixed {
  402. return $this->getMultiByKey('', $keys, $flags);
  403. }
  404. public function getMultiWithCasTokens(
  405. mixed $keys,
  406. inout mixed $cas_tokens,
  407. int $flags = 0,
  408. ): mixed {
  409. $result = $this->getMultiByKeyWithCasTokens(
  410. '',
  411. $keys,
  412. inout $cas_tokens,
  413. $flags,
  414. );
  415. return $result;
  416. }
  417. /**
  418. * Retrieve multiple items from a specific server
  419. *
  420. * @param string $server_key -
  421. * @param array $keys - Array of keys to retrieve.
  422. * @param string $cas_tokens - The variable to store the CAS tokens for
  423. * the found items.
  424. * @param int $flags - The flags for the get operation.
  425. *
  426. * @return array - Returns the array of found items.
  427. */
  428. <<__Native>>
  429. public function getMultiByKey(string $server_key,
  430. array $keys,
  431. int $flags = 0): mixed;
  432. <<__Native>>
  433. public function getMultiByKeyWithCasTokens(string $server_key,
  434. array $keys,
  435. <<__OutOnly>>
  436. inout mixed $cas_tokens,
  437. int $flags = 0): mixed;
  438. /**
  439. * Retrieve a Memcached option value
  440. *
  441. * @param int $option - One of the Memcached::OPT_* constants.
  442. *
  443. * @return mixed - Returns the value of the requested option, or FALSE
  444. * on error.
  445. */
  446. <<__Native>>
  447. public function getOption(int $option): mixed;
  448. /**
  449. * Return the result code of the last operation
  450. *
  451. * @return int - Result code of the last Memcached operation.
  452. */
  453. <<__Native>>
  454. public function getResultCode(): int;
  455. /**
  456. * Return the message describing the result of the last operation
  457. *
  458. * @return string - Message describing the result of the last Memcached
  459. * operation.
  460. */
  461. <<__Native>>
  462. public function getResultMessage(): string;
  463. /**
  464. * Map a key to a server
  465. *
  466. * @param string $server_key -
  467. *
  468. * @return array - Returns an array containing three keys of host,
  469. * port, and weight on success or FALSE on failure.
  470. */
  471. <<__Native>>
  472. public function getServerByKey(string $server_key): mixed;
  473. /**
  474. * Get the list of the servers in the pool
  475. *
  476. * @return array - The list of all servers in the server pool.
  477. */
  478. <<__Native>>
  479. public function getServerList(): array;
  480. /**
  481. * Clears all server from the list
  482. *
  483. * @return bool - Returns TRUE on success or FALSE on failure.
  484. */
  485. <<__Native>>
  486. public function resetServerList(): bool;
  487. /**
  488. * Get server pool statistics
  489. *
  490. * @return array - Array of server statistics, one entry per server.
  491. */
  492. <<__Native>>
  493. public function getStats(): mixed;
  494. /**
  495. * Get server pool version info
  496. *
  497. * @return array - Array of server versions, one entry per server.
  498. */
  499. <<__Native>>
  500. public function getVersion(): mixed;
  501. /**
  502. * Increment numeric item's value
  503. *
  504. * @param string $key - The key of the item to increment.
  505. * @param int $offset - The amount by which to increment the item's
  506. * value.
  507. * @param mixed $initial_value - The value to set the item to if it
  508. * doesn't currently exist. False to fail if the key does not exist.
  509. * @param int $expiry - The expiry time to set on the item.
  510. *
  511. * @return mixed - Returns new item's value on success. False if the key
  512. * doesn't exist.
  513. */
  514. <<__Native>>
  515. public function increment(string $key,
  516. int $offset = 1,
  517. mixed $initial_value = false,
  518. int $expiry = 0): mixed;
  519. /**
  520. * Increment numeric item's value, stored on a specific server
  521. *
  522. * @param string $server_key -
  523. * @param string $key - The key of the item to increment.
  524. * @param int $offset - The amount by which to increment the item's
  525. * value.
  526. * @param mixed $initial_value - The value to set the item to if it
  527. * doesn't currently exist. False to fail if the key does not exist.
  528. * @param int $expiry - The expiry time to set on the item.
  529. *
  530. * @return mixed - Returns new item's value on success. False if the key
  531. * doesn't exist and no initial_value was provided.
  532. */
  533. <<__Native>>
  534. public function incrementByKey(string $server_key,
  535. string $key,
  536. int $offset = 1,
  537. mixed $initial_value = false,
  538. int $expiry = 0): mixed;
  539. /**
  540. * Check if a persitent connection to memcache is being used.
  541. *
  542. * @return bool - Returns true if Memcache instance uses a persistent
  543. * connection, false otherwise.
  544. */
  545. <<__Native>>
  546. public function isPersistent(): bool;
  547. /**
  548. * Check if the instance was recently created
  549. *
  550. * @return bool - Returns the true if instance is recently created,
  551. * false otherwise.
  552. */
  553. <<__Native>>
  554. public function isPristine(): bool;
  555. /**
  556. * Prepend data to an existing item
  557. *
  558. * @param string $key - The key of the item to prepend the data to.
  559. * @param string $value - The string to prepend.
  560. *
  561. * @return bool - The Memcached::getResultCode will return
  562. * Memcached::RES_NOTSTORED if the key does not exist.
  563. */
  564. public function prepend(mixed $key,
  565. mixed $value): bool {
  566. return $this->prependByKey('', $key, $value);
  567. }
  568. /**
  569. * Prepend data to an existing item on a specific server
  570. *
  571. * @param string $server_key -
  572. * @param string $key - The key of the item to prepend the data to.
  573. * @param string $value - The string to prepend.
  574. *
  575. * @return bool - The Memcached::getResultCode will return
  576. * Memcached::RES_NOTSTORED if the key does not exist.
  577. */
  578. <<__Native>>
  579. public function prependByKey(string $server_key,
  580. string $key,
  581. string $value): bool;
  582. /**
  583. * Memcached::quit() closes any open connections to the memcache servers.
  584. * @return bool TRUE on success or FALSE on failure
  585. */
  586. <<__Native>>
  587. public function quit(): bool;
  588. /**
  589. * Replace the item under an existing key
  590. *
  591. * @param string $key -
  592. * @param mixed $value -
  593. * @param int $expiration -
  594. *
  595. * @return bool - The Memcached::getResultCode will return
  596. * Memcached::RES_NOTSTORED if the key does not exist.
  597. */
  598. public function replace(mixed $key,
  599. mixed $value,
  600. int $expiration = 0): bool {
  601. return $this->replaceByKey('', $key, $value, $expiration);
  602. }
  603. /**
  604. * Replace the item under an existing key on a specific server
  605. *
  606. * @param string $server_key -
  607. * @param string $key -
  608. * @param mixed $value -
  609. * @param int $expiration -
  610. *
  611. * @return bool - The Memcached::getResultCode will return
  612. * Memcached::RES_NOTSTORED if the key does not exist.
  613. */
  614. <<__Native>>
  615. public function replaceByKey(string $server_key,
  616. string $key,
  617. mixed $value,
  618. int $expiration = 0): bool;
  619. /**
  620. * Store an item
  621. *
  622. * @param string $key -
  623. * @param mixed $value -
  624. * @param int $expiration -
  625. *
  626. * @return bool -
  627. */
  628. public function set(mixed $key,
  629. mixed $value,
  630. int $expiration = 0): bool {
  631. return $this->setByKey('', $key, $value, $expiration);
  632. }
  633. /**
  634. * Store an item on a specific server
  635. *
  636. * @param string $server_key -
  637. * @param string $key -
  638. * @param mixed $value -
  639. * @param int $expiration -
  640. *
  641. * @return bool -
  642. */
  643. <<__Native>>
  644. public function setByKey(string $server_key,
  645. string $key,
  646. mixed $value,
  647. int $expiration = 0): bool;
  648. /**
  649. * Store multiple items
  650. *
  651. * @param array $items -
  652. * @param int $expiration -
  653. *
  654. * @return bool -
  655. */
  656. public function setMulti(array<string, mixed> $items,
  657. int $expiration = 0): bool {
  658. return $this->setMultiByKey('', $items, $expiration);
  659. }
  660. /**
  661. * Store multiple items on a specific server
  662. *
  663. * @param string $server_key -
  664. * @param array $items -
  665. * @param int $expiration -
  666. *
  667. * @return bool -
  668. */
  669. public function setMultiByKey(string $server_key,
  670. array<string, mixed> $items,
  671. int $expiration = 0): bool {
  672. foreach($items as $key => $value) {
  673. if (is_int($key)) {
  674. // numeric strings (e.g. '5') become integers as array keys
  675. $key = (string)$key;
  676. } elseif (!is_string($key)) {
  677. continue;
  678. }
  679. if (!$this->setByKey($server_key, $key, $value, $expiration)) {
  680. return false;
  681. }
  682. }
  683. return true;
  684. }
  685. /**
  686. * Set a Memcached option
  687. *
  688. * @param int $option -
  689. * @param mixed $value -
  690. *
  691. * @return bool -
  692. */
  693. <<__Native>>
  694. public function setOption(int $option,
  695. mixed $value): bool;
  696. /**
  697. * Set Memcached options
  698. *
  699. * @param array $options -
  700. *
  701. * @return bool -
  702. */
  703. public function setOptions(array<int, mixed> $options): bool {
  704. foreach($options as $option => $value) {
  705. if (!$this->setOption($option, $value)) {
  706. return false;
  707. }
  708. }
  709. return true;
  710. }
  711. /**
  712. * Set a new expiration on an item
  713. *
  714. * @param string $key - The key under which to store the value.
  715. * @param int $expiration - The expiration time, defaults to 0.
  716. *
  717. * @return bool - Returns TRUE on success or FALSE on failure.
  718. */
  719. public function touch(string $key,
  720. int $expiration = 0): bool {
  721. return $this->touchByKey('', $key, $expiration);
  722. }
  723. /**
  724. * Set a new expiration on an item on a specific server
  725. *
  726. * @param string $server_key - The key identifying the server to store the
  727. * value on or retrieve it from. Instead of hashing on the actual key for
  728. * the item, we hash on the server key when deciding which memcached server
  729. * to talk to. This allows related items to be grouped together on a single
  730. * server for efficiency with multi operations.
  731. * @param string $key - The key under which to store the value.
  732. * @param int $expiration - The expiration time, defaults to 0.
  733. *
  734. * @return bool - Returns TRUE on success or FALSE on failure.
  735. */
  736. <<__Native>>
  737. public function touchByKey(string $server_key,
  738. string $key,
  739. int $expiration = 0): bool;
  740. }
  741. class MemcachedException {
  742. }