git.m6w6.name Git - m6w6/libmemcached/blob - include/libmemcached-1.0/memcached.hpp

   1 /*
   2     +--------------------------------------------------------------------+
   3     | libmemcached - C/C++ Client Library for memcached                  |
   4     +--------------------------------------------------------------------+
   5     | Redistribution and use in source and binary forms, with or without |
   6     | modification, are permitted under the terms of the BSD license.    |
   7     | You should have received a copy of the license in a bundled file   |
   8     | named LICENSE; in case you did not receive a copy you can review   |
   9     | the terms online at: https://opensource.org/licenses/BSD-3-Clause  |
  10     +--------------------------------------------------------------------+
  11     | Copyright (c) 2006-2014 Brian Aker   https://datadifferential.com/ |
  12     | Copyright (c) 2020 Michael Wallner   <mike@php.net>                |
  13     +--------------------------------------------------------------------+
  14 */
  15
  16 #pragma once
  17
  18 #include "libmemcached-1.0/memcached.h"
  19 #if 0
  20 #  include "libmemcached/exception.hpp"
  21 #endif
  22
  23 #include <cstring>
  24 #include <sstream>
  25 #include <string>
  26 #include <vector>
  27 #include <map>
  28
  29 namespace memcache {
  30
  31 /**
  32  * This is the core memcached library (if later, other objects
  33  * are needed, they will be created from this class).
  34  */
  35 class Memcache {
  36 public:
  37   Memcache() { memc_ = memcached(NULL, 0); }
  38
  39   Memcache(const std::string &config) { memc_ = memcached(config.c_str(), config.size()); }
  40
  41   Memcache(const std::string &hostname, in_port_t port) {
  42     memc_ = memcached(NULL, 0);
  43     if (memc_) {
  44       memcached_server_add(memc_, hostname.c_str(), port);
  45     }
  46   }
  47
  48   Memcache(memcached_st *clone) { memc_ = memcached_clone(NULL, clone); }
  49
  50   Memcache(const Memcache &rhs) { memc_ = memcached_clone(NULL, rhs.getImpl()); }
  51
  52   Memcache &operator=(const Memcache &rhs) {
  53     if (this != &rhs) {
  54       memcached_free(memc_);
  55       memc_ = memcached_clone(NULL, rhs.getImpl());
  56     }
  57
  58     return *this;
  59   }
  60
  61   ~Memcache() { memcached_free(memc_); }
  62
  63   /**
  64    * Get the internal memcached_st *
  65    */
  66   const memcached_st *getImpl() const { return memc_; }
  67
  68   /**
  69    * Return an error string for the given return structure.
  70    *
  71    * @param[in] rc a memcached_return_t structure
  72    * @return error string corresponding to given return code in the library.
  73    */
  74   const std::string getError(memcached_return_t rc) const {
  75     /* first parameter to strerror is unused */
  76     return memcached_strerror(NULL, rc);
  77   }
  78
  79   bool error(std::string &error_message) const {
  80     if (memcached_failed(memcached_last_error(memc_))) {
  81       error_message += memcached_last_error_message(memc_);
  82       return true;
  83     }
  84
  85     return false;
  86   }
  87
  88   bool error() const {
  89     if (memcached_failed(memcached_last_error(memc_))) {
  90       return true;
  91     }
  92
  93     return false;
  94   }
  95
  96   bool error(memcached_return_t &arg) const {
  97     arg = memcached_last_error(memc_);
  98     return memcached_failed(arg);
  99   }
 100
 101   bool setBehavior(memcached_behavior_t flag, uint64_t data) {
 102     return (memcached_success(memcached_behavior_set(memc_, flag, data)));
 103   }
 104
 105   uint64_t getBehavior(memcached_behavior_t flag) { return memcached_behavior_get(memc_, flag); }
 106
 107   /**
 108    * Configure the memcache object
 109    *
 110    * @param[in] in_config configuration
 111    * @return true on success; false otherwise
 112    */
 113   bool configure(const std::string &configuration) {
 114     memcached_st *new_memc = memcached(configuration.c_str(), configuration.size());
 115
 116     if (new_memc) {
 117       memcached_free(memc_);
 118       memc_ = new_memc;
 119
 120       return true;
 121     }
 122
 123     return false;
 124   }
 125
 126   /**
 127    * Add a server to the list of memcached servers to use.
 128    *
 129    * @param[in] server_name name of the server to add
 130    * @param[in] port port number of server to add
 131    * @return true on success; false otherwise
 132    */
 133   bool addServer(const std::string &server_name, in_port_t port) {
 134     return memcached_success(memcached_server_add(memc_, server_name.c_str(), port));
 135   }
 136
 137   /**
 138    * Remove a server from the list of memcached servers to use.
 139    *
 140    * @param[in] server_name name of the server to remove
 141    * @param[in] port port number of server to remove
 142    * @return true on success; false otherwise
 143    */
 144   bool removeServer(const std::string &server_name, in_port_t port) {
 145     std::string tmp_str;
 146     std::ostringstream strstm;
 147     tmp_str.append(",");
 148     tmp_str.append(server_name);
 149     tmp_str.append(":");
 150     strstm << port;
 151     tmp_str.append(strstm.str());
 152
 153     // memcached_return_t rc= memcached_server_remove(server);
 154
 155     return false;
 156   }
 157
 158   /**
 159    * Fetches an individual value from the server. mget() must always
 160    * be called before using this method.
 161    *
 162    * @param[in] key key of object to fetch
 163    * @param[out] ret_val store returned object in this vector
 164    * @return a memcached return structure
 165    */
 166   memcached_return_t fetch(std::string &key, std::vector<char> &ret_val, uint32_t &flags,
 167                            uint64_t &cas_value) {
 168     memcached_return_t rc;
 169
 170     memcached_result_st *result;
 171     if ((result = memcached_fetch_result(memc_, NULL, &rc))) {
 172       // Key
 173       key.assign(memcached_result_key_value(result), memcached_result_key_length(result));
 174
 175       // Actual value, null terminated
 176       ret_val.reserve(memcached_result_length(result) + 1);
 177       ret_val.assign(memcached_result_value(result),
 178                      memcached_result_value(result) + memcached_result_length(result) + 1);
 179       ret_val.resize(memcached_result_length(result));
 180
 181       // Misc
 182       flags = memcached_result_flags(result);
 183       cas_value = memcached_result_cas(result);
 184     }
 185     memcached_result_free(result);
 186
 187     return rc;
 188   }
 189
 190   memcached_return_t fetch(std::string &key, std::vector<char> &ret_val) {
 191     uint32_t flags = 0;
 192     uint64_t cas_value = 0;
 193
 194     return fetch(key, ret_val, flags, cas_value);
 195   }
 196
 197   /**
 198    * Fetches an individual value from the server.
 199    *
 200    * @param[in] key key of object whose value to get
 201    * @param[out] ret_val object that is retrieved is stored in
 202    *                     this vector
 203    * @return true on success; false otherwise
 204    */
 205   bool get(const std::string &key, std::vector<char> &ret_val) {
 206     uint32_t flags = 0;
 207     memcached_return_t rc;
 208     size_t value_length = 0;
 209
 210     char *value = memcached_get(memc_, key.c_str(), key.length(), &value_length, &flags, &rc);
 211     if (value != NULL && ret_val.empty()) {
 212       ret_val.reserve(value_length + 1); // Always provide null
 213       ret_val.assign(value, value + value_length + 1);
 214       ret_val.resize(value_length);
 215       free(value);
 216
 217       return true;
 218     }
 219
 220     return false;
 221   }
 222
 223   /**
 224    * Fetches an individual from a server which is specified by
 225    * the master_key parameter that is used for determining which
 226    * server an object was stored in if key partitioning was
 227    * used for storage.
 228    *
 229    * @param[in] master_key key that specifies server object is stored on
 230    * @param[in] key key of object whose value to get
 231    * @param[out] ret_val object that is retrieved is stored in
 232    *                     this vector
 233    * @return true on success; false otherwise
 234    */
 235   bool getByKey(const std::string &master_key, const std::string &key, std::vector<char> &ret_val) {
 236     uint32_t flags = 0;
 237     memcached_return_t rc;
 238     size_t value_length = 0;
 239
 240     char *value = memcached_get_by_key(memc_, master_key.c_str(), master_key.length(), key.c_str(),
 241                                        key.length(), &value_length, &flags, &rc);
 242     if (value) {
 243       ret_val.reserve(value_length + 1); // Always provide null
 244       ret_val.assign(value, value + value_length + 1);
 245       ret_val.resize(value_length);
 246       free(value);
 247
 248       return true;
 249     }
 250     return false;
 251   }
 252
 253   /**
 254    * Selects multiple keys at once. This method always
 255    * works asynchronously.
 256    *
 257    * @param[in] keys vector of keys to select
 258    * @return true if all keys are found
 259    */
 260   bool mget(const std::vector<std::string> &keys) {
 261     std::vector<const char *> real_keys;
 262     std::vector<size_t> key_len;
 263     /*
 264      * Construct an array which will contain the length
 265      * of each of the strings in the input vector. Also, to
 266      * interface with the memcached C API, we need to convert
 267      * the vector of std::string's to a vector of char *.
 268      */
 269     real_keys.reserve(keys.size());
 270     key_len.reserve(keys.size());
 271
 272     std::vector<std::string>::const_iterator it = keys.begin();
 273
 274     while (it != keys.end()) {
 275       real_keys.push_back(const_cast<char *>((*it).c_str()));
 276       key_len.push_back((*it).length());
 277       ++it;
 278     }
 279
 280     /*
 281      * If the std::vector of keys is empty then we cannot
 282      * call memcached_mget as we will get undefined behavior.
 283      */
 284     if (not real_keys.empty()) {
 285       return memcached_success(memcached_mget(memc_, &real_keys[0], &key_len[0], real_keys.size()));
 286     }
 287
 288     return false;
 289   }
 290
 291   /**
 292    * Writes an object to the server. If the object already exists, it will
 293    * overwrite the existing object. This method always returns true
 294    * when using non-blocking mode unless a network error occurs.
 295    *
 296    * @param[in] key key of object to write to server
 297    * @param[in] value value of object to write to server
 298    * @param[in] expiration time to keep the object stored in the server for
 299    * @param[in] flags flags to store with the object
 300    * @return true on succcess; false otherwise
 301    */
 302   bool set(const std::string &key, const std::vector<char> &value, time_t expiration,
 303            uint32_t flags) {
 304     memcached_return_t rc = memcached_set(memc_, key.c_str(), key.length(), value.data(),
 305                                           value.size(), expiration, flags);
 306     return memcached_success(rc);
 307   }
 308
 309   bool set(const std::string &key, const char *value, const size_t value_length, time_t expiration,
 310            uint32_t flags) {
 311     memcached_return_t rc =
 312         memcached_set(memc_, key.c_str(), key.length(), value, value_length, expiration, flags);
 313     return memcached_success(rc);
 314   }
 315
 316   /**
 317    * Writes an object to a server specified by the master_key parameter.
 318    * If the object already exists, it will overwrite the existing object.
 319    *
 320    * @param[in] master_key key that specifies server to write to
 321    * @param[in] key key of object to write to server
 322    * @param[in] value value of object to write to server
 323    * @param[in] expiration time to keep the object stored in the server for
 324    * @param[in] flags flags to store with the object
 325    * @return true on succcess; false otherwise
 326    */
 327   bool setByKey(const std::string &master_key, const std::string &key,
 328                 const std::vector<char> &value, time_t expiration, uint32_t flags) {
 329     return memcached_success(memcached_set_by_key(memc_, master_key.c_str(), master_key.length(),
 330                                                   key.c_str(), key.length(), &value[0],
 331                                                   value.size(), expiration, flags));
 332   }
 333
 334   /**
 335    * Writes a list of objects to the server. Objects are specified by
 336    * 2 vectors - 1 vector of keys and 1 vector of values.
 337    *
 338    * @param[in] keys vector of keys of objects to write to server
 339    * @param[in] values vector of values of objects to write to server
 340    * @param[in] expiration time to keep the objects stored in server for
 341    * @param[in] flags flags to store with the objects
 342    * @return true on success; false otherwise
 343    */
 344   bool setAll(const std::vector<std::string> &keys, const std::vector<std::vector<char> *> &values,
 345               time_t expiration, uint32_t flags) {
 346     bool retval = true;
 347     std::vector<std::string>::const_iterator key_it = keys.begin();
 348     std::vector<std::vector<char> *>::const_iterator val_it = values.begin();
 349     while (key_it != keys.end()) {
 350       retval = set((*key_it), *(*val_it), expiration, flags);
 351       if (retval == false) {
 352         return retval;
 353       }
 354       ++key_it;
 355       ++val_it;
 356     }
 357     return retval;
 358   }
 359
 360   /**
 361    * Writes a list of objects to the server. Objects are specified by
 362    * a map of keys to values.
 363    *
 364    * @param[in] key_value_map map of keys and values to store in server
 365    * @param[in] expiration time to keep the objects stored in server for
 366    * @param[in] flags flags to store with the objects
 367    * @return true on success; false otherwise
 368    */
 369   bool setAll(const std::map<const std::string, std::vector<char>> &key_value_map,
 370               time_t expiration, uint32_t flags) {
 371     std::map<const std::string, std::vector<char>>::const_iterator it = key_value_map.begin();
 372
 373     while (it != key_value_map.end()) {
 374       if (!set(it->first, it->second, expiration, flags)) {
 375         // We should tell the user what the key that failed was
 376         return false;
 377       }
 378       ++it;
 379     }
 380
 381     return true;
 382   }
 383
 384   /**
 385    * Increment the value of the object associated with the specified
 386    * key by the offset given. The resulting value is saved in the value
 387    * parameter.
 388    *
 389    * @param[in] key key of object in server whose value to increment
 390    * @param[in] offset amount to increment object's value by
 391    * @param[out] value store the result of the increment here
 392    * @return true on success; false otherwise
 393    */
 394   bool increment(const std::string &key, uint32_t offset, uint64_t *value) {
 395     return memcached_success(memcached_increment(memc_, key.c_str(), key.length(), offset, value));
 396   }
 397
 398   /**
 399    * Decrement the value of the object associated with the specified
 400    * key by the offset given. The resulting value is saved in the value
 401    * parameter.
 402    *
 403    * @param[in] key key of object in server whose value to decrement
 404    * @param[in] offset amount to increment object's value by
 405    * @param[out] value store the result of the decrement here
 406    * @return true on success; false otherwise
 407    */
 408   bool decrement(const std::string &key, uint32_t offset, uint64_t *value) {
 409     return memcached_success(memcached_decrement(memc_, key.c_str(), key.length(), offset, value));
 410   }
 411
 412   /**
 413    * Add an object with the specified key and value to the server. This
 414    * function returns false if the object already exists on the server.
 415    *
 416    * @param[in] key key of object to add
 417    * @param[in] value of object to add
 418    * @return true on success; false otherwise
 419    */
 420   bool add(const std::string &key, const std::vector<char> &value) {
 421     return memcached_success(
 422         memcached_add(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
 423   }
 424
 425   /**
 426    * Add an object with the specified key and value to the server. This
 427    * function returns false if the object already exists on the server. The
 428    * server to add the object to is specified by the master_key parameter.
 429    *
 430    * @param[in[ master_key key of server to add object to
 431    * @param[in] key key of object to add
 432    * @param[in] value of object to add
 433    * @return true on success; false otherwise
 434    */
 435   bool addByKey(const std::string &master_key, const std::string &key,
 436                 const std::vector<char> &value) {
 437     return memcached_success(memcached_add_by_key(memc_, master_key.c_str(), master_key.length(),
 438                                                   key.c_str(), key.length(), &value[0],
 439                                                   value.size(), 0, 0));
 440   }
 441
 442   /**
 443    * Replaces an object on the server. This method only succeeds
 444    * if the object is already present on the server.
 445    *
 446    * @param[in] key key of object to replace
 447    * @param[in[ value value to replace object with
 448    * @return true on success; false otherwise
 449    */
 450   bool replace(const std::string &key, const std::vector<char> &value) {
 451     return memcached_success(
 452         memcached_replace(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
 453   }
 454
 455   /**
 456    * Replaces an object on the server. This method only succeeds
 457    * if the object is already present on the server. The server
 458    * to replace the object on is specified by the master_key param.
 459    *
 460    * @param[in] master_key key of server to replace object on
 461    * @param[in] key key of object to replace
 462    * @param[in[ value value to replace object with
 463    * @return true on success; false otherwise
 464    */
 465   bool replaceByKey(const std::string &master_key, const std::string &key,
 466                     const std::vector<char> &value) {
 467     return memcached_success(memcached_replace_by_key(memc_, master_key.c_str(),
 468                                                       master_key.length(), key.c_str(),
 469                                                       key.length(), &value[0], value.size(), 0, 0));
 470   }
 471
 472   /**
 473    * Places a segment of data before the last piece of data stored.
 474    *
 475    * @param[in] key key of object whose value we will prepend data to
 476    * @param[in] value data to prepend to object's value
 477    * @return true on success; false otherwise
 478    */
 479   bool prepend(const std::string &key, const std::vector<char> &value) {
 480     return memcached_success(
 481         memcached_prepend(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
 482   }
 483
 484   /**
 485    * Places a segment of data before the last piece of data stored. The
 486    * server on which the object where we will be prepending data is stored
 487    * on is specified by the master_key parameter.
 488    *
 489    * @param[in] master_key key of server where object is stored
 490    * @param[in] key key of object whose value we will prepend data to
 491    * @param[in] value data to prepend to object's value
 492    * @return true on success; false otherwise
 493    */
 494   bool prependByKey(const std::string &master_key, const std::string &key,
 495                     const std::vector<char> &value) {
 496     return memcached_success(memcached_prepend_by_key(memc_, master_key.c_str(),
 497                                                       master_key.length(), key.c_str(),
 498                                                       key.length(), &value[0], value.size(), 0, 0));
 499   }
 500
 501   /**
 502    * Places a segment of data at the end of the last piece of data stored.
 503    *
 504    * @param[in] key key of object whose value we will append data to
 505    * @param[in] value data to append to object's value
 506    * @return true on success; false otherwise
 507    */
 508   bool append(const std::string &key, const std::vector<char> &value) {
 509     return memcached_success(
 510         memcached_append(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
 511   }
 512
 513   /**
 514    * Places a segment of data at the end of the last piece of data stored. The
 515    * server on which the object where we will be appending data is stored
 516    * on is specified by the master_key parameter.
 517    *
 518    * @param[in] master_key key of server where object is stored
 519    * @param[in] key key of object whose value we will append data to
 520    * @param[in] value data to append to object's value
 521    * @return true on success; false otherwise
 522    */
 523   bool appendByKey(const std::string &master_key, const std::string &key,
 524                    const std::vector<char> &value) {
 525     return memcached_success(memcached_append_by_key(memc_, master_key.c_str(), master_key.length(),
 526                                                      key.c_str(), key.length(), &value[0],
 527                                                      value.size(), 0, 0));
 528   }
 529
 530   /**
 531    * Overwrite data in the server as long as the cas_arg value
 532    * is still the same in the server.
 533    *
 534    * @param[in] key key of object in server
 535    * @param[in] value value to store for object in server
 536    * @param[in] cas_arg "cas" value
 537    */
 538   bool cas(const std::string &key, const std::vector<char> &value, uint64_t cas_arg) {
 539     return memcached_success(
 540         memcached_cas(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0, cas_arg));
 541   }
 542
 543   /**
 544    * Overwrite data in the server as long as the cas_arg value
 545    * is still the same in the server. The server to use is
 546    * specified by the master_key parameter.
 547    *
 548    * @param[in] master_key specifies server to operate on
 549    * @param[in] key key of object in server
 550    * @param[in] value value to store for object in server
 551    * @param[in] cas_arg "cas" value
 552    */
 553   bool casByKey(const std::string &master_key, const std::string &key,
 554                 const std::vector<char> &value, uint64_t cas_arg) {
 555     return memcached_success(memcached_cas_by_key(memc_, master_key.c_str(), master_key.length(),
 556                                                   key.c_str(), key.length(), &value[0],
 557                                                   value.size(), 0, 0, cas_arg));
 558   }
 559
 560   /**
 561    * Delete an object from the server specified by the key given.
 562    *
 563    * @param[in] key key of object to delete
 564    * @return true on success; false otherwise
 565    */
 566   bool remove(const std::string &key) {
 567     return memcached_success(memcached_delete(memc_, key.c_str(), key.length(), 0));
 568   }
 569
 570   /**
 571    * Delete an object from the server specified by the key given.
 572    *
 573    * @param[in] key key of object to delete
 574    * @param[in] expiration time to delete the object after
 575    * @return true on success; false otherwise
 576    */
 577   bool remove(const std::string &key, time_t expiration) {
 578     return memcached_success(memcached_delete(memc_, key.c_str(), key.length(), expiration));
 579   }
 580
 581   /**
 582    * Delete an object from the server specified by the key given.
 583    *
 584    * @param[in] master_key specifies server to remove object from
 585    * @param[in] key key of object to delete
 586    * @return true on success; false otherwise
 587    */
 588   bool removeByKey(const std::string &master_key, const std::string &key) {
 589     return memcached_success(memcached_delete_by_key(memc_, master_key.c_str(), master_key.length(),
 590                                                      key.c_str(), key.length(), 0));
 591   }
 592
 593   /**
 594    * Delete an object from the server specified by the key given.
 595    *
 596    * @param[in] master_key specifies server to remove object from
 597    * @param[in] key key of object to delete
 598    * @param[in] expiration time to delete the object after
 599    * @return true on success; false otherwise
 600    */
 601   bool removeByKey(const std::string &master_key, const std::string &key, time_t expiration) {
 602     return memcached_success(memcached_delete_by_key(memc_, master_key.c_str(), master_key.length(),
 603                                                      key.c_str(), key.length(), expiration));
 604   }
 605
 606   /**
 607    * Wipe the contents of memcached servers.
 608    *
 609    * @param[in] expiration time to wait until wiping contents of
 610    *                       memcached servers
 611    * @return true on success; false otherwise
 612    */
 613   bool flush(time_t expiration = 0) {
 614     return memcached_success(memcached_flush(memc_, expiration));
 615   }
 616
 617   /**
 618    * Get the library version string.
 619    * @return std::string containing a copy of the library version string.
 620    */
 621   const std::string libVersion() const {
 622     const char *ver = memcached_lib_version();
 623     const std::string version(ver);
 624     return version;
 625   }
 626
 627   /**
 628    * Retrieve memcached statistics. Populate a std::map with the retrieved
 629    * stats. Each server will map to another std::map of the key:value stats.
 630    *
 631    * @param[out] stats_map a std::map to be populated with the memcached
 632    *                       stats
 633    * @return true on success; false otherwise
 634    */
 635   bool getStats(std::map<std::string, std::map<std::string, std::string>> &stats_map) {
 636     memcached_return_t rc;
 637     memcached_stat_st *stats = memcached_stat(memc_, NULL, &rc);
 638
 639     if (rc != MEMCACHED_SUCCESS && rc != MEMCACHED_SOME_ERRORS) {
 640       return false;
 641     }
 642
 643     uint32_t server_count = memcached_server_count(memc_);
 644
 645     /*
 646      * For each memcached server, construct a std::map for its stats and add
 647      * it to the std::map of overall stats.
 648      */
 649     for (uint32_t x = 0; x < server_count; x++) {
 650       const memcached_instance_st *instance = memcached_server_instance_by_position(memc_, x);
 651       std::ostringstream strstm;
 652       std::string server_name(memcached_server_name(instance));
 653       server_name.append(":");
 654       strstm << memcached_server_port(instance);
 655       server_name.append(strstm.str());
 656
 657       std::map<std::string, std::string> server_stats;
 658       char **list = memcached_stat_get_keys(memc_, &stats[x], &rc);
 659       for (char **ptr = list; *ptr; ptr++) {
 660         char *value = memcached_stat_get_value(memc_, &stats[x], *ptr, &rc);
 661         server_stats[*ptr] = value;
 662         free(value);
 663       }
 664
 665       stats_map[server_name] = server_stats;
 666       free(list);
 667     }
 668
 669     memcached_stat_free(memc_, stats);
 670     return true;
 671   }
 672
 673 private:
 674   memcached_st *memc_;
 675 };
 676
 677 } // namespace memcache