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

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