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