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 #ifndef LIBMEMCACHEDPP_H
  16 #define LIBMEMCACHEDPP_H
  17
  18 #include <libmemcached/memcached.h>
  19 #include <libmemcached/exception.hpp>
  20
  21 #include <string.h>
  22
  23 #include <sstream>
  24 #include <string>
  25 #include <vector>
  26 #include <map>
  27
  28 namespace memcache
  29 {
  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 {
  37 public:
  38
  39   Memcache()
  40     :
  41       servers_list(),
  42       memc(),
  43       servers(NULL),
  44       result()
  45   {
  46     memcached_create(&memc);
  47   }
  48
  49   Memcache(const std::string &in_servers_list)
  50     :
  51       servers_list(in_servers_list),
  52       memc(),
  53       servers(NULL),
  54       result()
  55   {
  56     memcached_create(&memc);
  57     servers= memcached_servers_parse(servers_list.c_str());
  58     memcached_server_push(&memc, servers);
  59   }
  60
  61   Memcache(const std::string &hostname,
  62            in_port_t port)
  63     :
  64       servers_list(),
  65       memc(),
  66       servers(NULL),
  67       result()
  68   {
  69     memcached_create(&memc);
  70     servers_list.append(hostname);
  71     servers_list.append(":");
  72     std::ostringstream strsmt;
  73     strsmt << port;
  74     servers_list.append(strsmt.str());
  75     servers= memcached_servers_parse(servers_list.c_str());
  76     memcached_server_push(&memc, servers);
  77   }
  78
  79   Memcache(memcached_st *clone)
  80     :
  81       servers_list(),
  82       memc(),
  83       servers(NULL),
  84       result()
  85   {
  86     memcached_clone(&memc, clone);
  87   }
  88
  89   Memcache(const Memcache &rhs)
  90     :
  91       servers_list(rhs.servers_list),
  92       memc(),
  93       servers(NULL),
  94       result()
  95   {
  96     memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
  97     servers= memcached_servers_parse(servers_list.c_str());
  98     memcached_server_push(&memc, servers);
  99   }
 100
 101   Memcache &operator=(const Memcache &rhs)
 102   {
 103     if (this != &rhs)
 104     {
 105       memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
 106       servers= memcached_servers_parse(servers_list.c_str());
 107       memcached_server_push(&memc, servers);
 108     }
 109     return *this;
 110   }
 111
 112   ~Memcache()
 113   {
 114     memcached_free(&memc);
 115     memcached_server_list_free(servers);
 116   }
 117
 118   /**
 119    * Get the internal memcached_st *
 120    */
 121   memcached_st &getImpl()
 122   {
 123     return memc;
 124   }
 125
 126   /**
 127    * Get the internal memcached_st *
 128    */
 129   const memcached_st &getImpl() const
 130   {
 131     return memc;
 132   }
 133
 134   /**
 135    * Return an error string for the given return structure.
 136    *
 137    * @param[in] rc a memcached_return_t structure
 138    * @return error string corresponding to given return code in the library.
 139    */
 140   const std::string getError(memcached_return_t rc) const
 141   {
 142     /* first parameter to strerror is unused */
 143     return memcached_strerror(NULL, rc);
 144   }
 145
 146
 147   bool setBehavior(memcached_behavior_t flag, uint64_t data)
 148   {
 149     memcached_return_t rc;
 150     rc= memcached_behavior_set(&memc, flag, data);
 151     return (rc == MEMCACHED_SUCCESS);
 152   }
 153
 154   uint64_t getBehavior(memcached_behavior_t flag) {
 155     return memcached_behavior_get(&memc, flag);
 156   }
 157
 158   /**
 159    * Return the string which contains the list of memcached servers being
 160    * used.
 161    *
 162    * @return a std::string containing the list of memcached servers
 163    */
 164   const std::string getServersList() const
 165   {
 166     return servers_list;
 167   }
 168
 169   /**
 170    * Set the list of memcached servers to use.
 171    *
 172    * @param[in] in_servers_list list of servers
 173    * @return true on success; false otherwise
 174    */
 175   bool setServers(const std::string &in_servers_list)
 176   {
 177     servers_list.assign(in_servers_list);
 178     servers= memcached_servers_parse(in_servers_list.c_str());
 179     memcached_server_push(&memc, servers);
 180     return (servers == NULL);
 181   }
 182
 183   /**
 184    * Add a server to the list of memcached servers to use.
 185    *
 186    * @param[in] server_name name of the server to add
 187    * @param[in] port port number of server to add
 188    * @return true on success; false otherwise
 189    */
 190   bool addServer(const std::string &server_name, in_port_t port)
 191   {
 192     memcached_return_t rc;
 193     std::ostringstream strstm;
 194     servers_list.append(",");
 195     servers_list.append(server_name);
 196     servers_list.append(":");
 197     strstm << port;
 198     servers_list.append(strstm.str());
 199     servers= memcached_server_list_append(servers,
 200                                           server_name.c_str(),
 201                                           port,
 202                                           &rc);
 203     memcached_server_push(&memc, servers);
 204     return (rc == MEMCACHED_SUCCESS);
 205   }
 206
 207   /**
 208    * Remove a server from the list of memcached servers to use.
 209    *
 210    * @param[in] server_name name of the server to remove
 211    * @param[in] port port number of server to remove
 212    * @return true on success; false otherwise
 213    */
 214   bool removeServer(const std::string &server_name, in_port_t port)
 215   {
 216     std::string tmp_str;
 217     std::ostringstream strstm;
 218     tmp_str.append(",");
 219     tmp_str.append(server_name);
 220     tmp_str.append(":");
 221     strstm << port;
 222     tmp_str.append(strstm.str());
 223     memcached_server_st *server= memcached_servers_parse(tmp_str.c_str());
 224
 225     memcached_return_t rc= memcached_server_remove(server);
 226
 227     return (rc == MEMCACHED_SUCCESS);
 228   }
 229
 230   /**
 231    * Fetches an individual value from the server. mget() must always
 232    * be called before using this method.
 233    *
 234    * @param[in] key key of object to fetch
 235    * @param[out] ret_val store returned object in this vector
 236    * @return a memcached return structure
 237    */
 238   memcached_return_t fetch(std::string &key,
 239                          std::vector<char> &ret_val)
 240   {
 241     char ret_key[MEMCACHED_MAX_KEY];
 242     size_t value_length= 0;
 243     size_t key_length= 0;
 244     memcached_return_t rc;
 245     uint32_t flags= 0;
 246     char *value= memcached_fetch(&memc, ret_key, &key_length,
 247                                  &value_length, &flags, &rc);
 248     if (value && ret_val.empty())
 249     {
 250       ret_val.reserve(value_length);
 251       ret_val.assign(value, value + value_length);
 252       key.assign(ret_key);
 253       free(value);
 254     }
 255     else if (value)
 256     {
 257       free(value);
 258     }
 259
 260     return rc;
 261   }
 262
 263   /**
 264    * Fetches an individual value from the server.
 265    *
 266    * @param[in] key key of object whose value to get
 267    * @param[out] ret_val object that is retrieved is stored in
 268    *                     this vector
 269    * @return true on success; false otherwise
 270    */
 271   bool get(const std::string &key,
 272            std::vector<char> &ret_val) throw (Error)
 273   {
 274     uint32_t flags= 0;
 275     memcached_return_t rc;
 276     size_t value_length= 0;
 277
 278     if (key.empty())
 279     {
 280       throw(Error("the key supplied is empty!", false));
 281     }
 282     char *value= memcached_get(&memc, key.c_str(), key.length(),
 283                                &value_length, &flags, &rc);
 284     if (value != NULL && ret_val.empty())
 285     {
 286       ret_val.reserve(value_length);
 287       ret_val.assign(value, value + value_length);
 288       free(value);
 289       return true;
 290     }
 291     return false;
 292   }
 293
 294   /**
 295    * Fetches an individual from a server which is specified by
 296    * the master_key parameter that is used for determining which
 297    * server an object was stored in if key partitioning was
 298    * used for storage.
 299    *
 300    * @param[in] master_key key that specifies server object is stored on
 301    * @param[in] key key of object whose value to get
 302    * @param[out] ret_val object that is retrieved is stored in
 303    *                     this vector
 304    * @return true on success; false otherwise
 305    */
 306   bool getByKey(const std::string &master_key,
 307                 const std::string &key,
 308                 std::vector<char> &ret_val) throw(Error)
 309   {
 310     uint32_t flags= 0;
 311     memcached_return_t rc;
 312     size_t value_length= 0;
 313
 314     if (master_key.empty() || key.empty())
 315     {
 316       throw(Error("the master key or key supplied is empty!", false));
 317     }
 318     char *value= memcached_get_by_key(&memc,
 319                                       master_key.c_str(), master_key.length(),
 320                                       key.c_str(), key.length(),
 321                                       &value_length, &flags, &rc);
 322     if (value)
 323     {
 324       ret_val.reserve(value_length);
 325       ret_val.assign(value, value + value_length);
 326       free(value);
 327       return true;
 328     }
 329     return false;
 330   }
 331
 332   /**
 333    * Selects multiple keys at once. This method always
 334    * works asynchronously.
 335    *
 336    * @param[in] keys vector of keys to select
 337    * @return true if all keys are found
 338    */
 339   bool mget(std::vector<std::string> &keys)
 340   {
 341     std::vector<const char *> real_keys;
 342     std::vector<size_t> key_len;
 343     /*
 344      * Construct an array which will contain the length
 345      * of each of the strings in the input vector. Also, to
 346      * interface with the memcached C API, we need to convert
 347      * the vector of std::string's to a vector of char *.
 348      */
 349     real_keys.reserve(keys.size());
 350     key_len.reserve(keys.size());
 351
 352     std::vector<std::string>::iterator it= keys.begin();
 353
 354     while (it != keys.end())
 355     {
 356       real_keys.push_back(const_cast<char *>((*it).c_str()));
 357       key_len.push_back((*it).length());
 358       ++it;
 359     }
 360
 361     /*
 362      * If the std::vector of keys is empty then we cannot
 363      * call memcached_mget as we will get undefined behavior.
 364      */
 365     if (! real_keys.empty())
 366     {
 367       memcached_return_t rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
 368                                           real_keys.size());
 369       return (rc == MEMCACHED_SUCCESS);
 370     }
 371
 372     return false;
 373   }
 374
 375   /**
 376    * Writes an object to the server. If the object already exists, it will
 377    * overwrite the existing object. This method always returns true
 378    * when using non-blocking mode unless a network error occurs.
 379    *
 380    * @param[in] key key of object to write to server
 381    * @param[in] value value of object to write to server
 382    * @param[in] expiration time to keep the object stored in the server for
 383    * @param[in] flags flags to store with the object
 384    * @return true on succcess; false otherwise
 385    */
 386   bool set(const std::string &key,
 387            const std::vector<char> &value,
 388            time_t expiration,
 389            uint32_t flags) throw(Error)
 390   {
 391     if (key.empty() || value.empty())
 392     {
 393       throw(Error("the key or value supplied is empty!", false));
 394     }
 395     memcached_return_t rc= memcached_set(&memc,
 396                                        key.c_str(), key.length(),
 397                                        &value[0], value.size(),
 398                                        expiration, flags);
 399     return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
 400   }
 401
 402   /**
 403    * Writes an object to a server specified by the master_key parameter.
 404    * If the object already exists, it will overwrite the existing object.
 405    *
 406    * @param[in] master_key key that specifies server to write to
 407    * @param[in] key key of object to write to server
 408    * @param[in] value value of object to write to server
 409    * @param[in] expiration time to keep the object stored in the server for
 410    * @param[in] flags flags to store with the object
 411    * @return true on succcess; false otherwise
 412    */
 413   bool setByKey(const std::string &master_key,
 414                 const std::string &key,
 415                 const std::vector<char> &value,
 416                 time_t expiration,
 417                 uint32_t flags) throw(Error)
 418   {
 419     if (master_key.empty() ||
 420         key.empty() ||
 421         value.empty())
 422     {
 423       throw(Error("the key or value supplied is empty!", false));
 424     }
 425     memcached_return_t rc= memcached_set_by_key(&memc, master_key.c_str(),
 426                                               master_key.length(),
 427                                               key.c_str(), key.length(),
 428                                               &value[0], value.size(),
 429                                               expiration,
 430                                               flags);
 431     return (rc == MEMCACHED_SUCCESS);
 432   }
 433
 434   /**
 435    * Writes a list of objects to the server. Objects are specified by
 436    * 2 vectors - 1 vector of keys and 1 vector of values.
 437    *
 438    * @param[in] keys vector of keys of objects to write to server
 439    * @param[in] values vector of values of objects to write to server
 440    * @param[in] expiration time to keep the objects stored in server for
 441    * @param[in] flags flags to store with the objects
 442    * @return true on success; false otherwise
 443    */
 444   bool setAll(std::vector<std::string> &keys,
 445               std::vector< std::vector<char> *> &values,
 446               time_t expiration,
 447               uint32_t flags) throw(Error)
 448   {
 449     if (keys.size() != values.size())
 450     {
 451       throw(Error("The number of keys and values do not match!", false));
 452     }
 453     bool retval= true;
 454     std::vector<std::string>::iterator key_it= keys.begin();
 455     std::vector< std::vector<char> *>::iterator val_it= values.begin();
 456     while (key_it != keys.end())
 457     {
 458       retval= set((*key_it), *(*val_it), expiration, flags);
 459       if (retval == false)
 460       {
 461         return retval;
 462       }
 463       ++key_it;
 464       ++val_it;
 465     }
 466     return retval;
 467   }
 468
 469   /**
 470    * Writes a list of objects to the server. Objects are specified by
 471    * a map of keys to values.
 472    *
 473    * @param[in] key_value_map map of keys and values to store in server
 474    * @param[in] expiration time to keep the objects stored in server for
 475    * @param[in] flags flags to store with the objects
 476    * @return true on success; false otherwise
 477    */
 478   bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
 479               time_t expiration,
 480               uint32_t flags) throw(Error)
 481   {
 482     if (key_value_map.empty())
 483     {
 484       throw(Error("The key/values are not properly set!", false));
 485     }
 486     bool retval= true;
 487     std::map<const std::string, std::vector<char> >::iterator it=
 488       key_value_map.begin();
 489     while (it != key_value_map.end())
 490     {
 491       retval= set(it->first, it->second, expiration, flags);
 492       if (retval == false)
 493       {
 494         std::string err_buff("There was an error setting the key ");
 495         err_buff.append(it->first);
 496         throw(Error(err_buff, false));
 497       }
 498       ++it;
 499     }
 500     return true;
 501   }
 502
 503   /**
 504    * Increment the value of the object associated with the specified
 505    * key by the offset given. The resulting value is saved in the value
 506    * parameter.
 507    *
 508    * @param[in] key key of object in server whose value to increment
 509    * @param[in] offset amount to increment object's value by
 510    * @param[out] value store the result of the increment here
 511    * @return true on success; false otherwise
 512    */
 513   bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
 514   {
 515     if (key.empty())
 516     {
 517       throw(Error("the key supplied is empty!", false));
 518     }
 519     memcached_return_t rc= memcached_increment(&memc, key.c_str(), key.length(),
 520                                              offset, value);
 521     return (rc == MEMCACHED_SUCCESS);
 522   }
 523
 524   /**
 525    * Decrement the value of the object associated with the specified
 526    * key by the offset given. The resulting value is saved in the value
 527    * parameter.
 528    *
 529    * @param[in] key key of object in server whose value to decrement
 530    * @param[in] offset amount to increment object's value by
 531    * @param[out] value store the result of the decrement here
 532    * @return true on success; false otherwise
 533    */
 534   bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
 535     throw(Error)
 536   {
 537     if (key.empty())
 538     {
 539       throw(Error("the key supplied is empty!", false));
 540     }
 541     memcached_return_t rc= memcached_decrement(&memc, key.c_str(),
 542                                              key.length(),
 543                                              offset, value);
 544     return (rc == MEMCACHED_SUCCESS);
 545   }
 546
 547
 548   /**
 549    * Add an object with the specified key and value to the server. This
 550    * function returns false if the object already exists on the server.
 551    *
 552    * @param[in] key key of object to add
 553    * @param[in] value of object to add
 554    * @return true on success; false otherwise
 555    */
 556   bool add(const std::string &key, const std::vector<char> &value)
 557     throw(Error)
 558   {
 559     if (key.empty() || value.empty())
 560     {
 561       throw(Error("the key or value supplied is empty!", false));
 562     }
 563     memcached_return_t rc= memcached_add(&memc, key.c_str(), key.length(),
 564                                        &value[0], value.size(), 0, 0);
 565     return (rc == MEMCACHED_SUCCESS);
 566   }
 567
 568   /**
 569    * Add an object with the specified key and value to the server. This
 570    * function returns false if the object already exists on the server. The
 571    * server to add the object to is specified by the master_key parameter.
 572    *
 573    * @param[in[ master_key key of server to add object to
 574    * @param[in] key key of object to add
 575    * @param[in] value of object to add
 576    * @return true on success; false otherwise
 577    */
 578   bool addByKey(const std::string &master_key,
 579                 const std::string &key,
 580                 const std::vector<char> &value) throw(Error)
 581   {
 582     if (master_key.empty() ||
 583         key.empty() ||
 584         value.empty())
 585     {
 586       throw(Error("the master key or key supplied is empty!", false));
 587     }
 588     memcached_return_t rc= memcached_add_by_key(&memc,
 589                                               master_key.c_str(),
 590                                               master_key.length(),
 591                                               key.c_str(),
 592                                               key.length(),
 593                                               &value[0],
 594                                               value.size(),
 595                                               0, 0);
 596     return (rc == MEMCACHED_SUCCESS);
 597   }
 598
 599   /**
 600    * Replaces an object on the server. This method only succeeds
 601    * if the object is already present on the server.
 602    *
 603    * @param[in] key key of object to replace
 604    * @param[in[ value value to replace object with
 605    * @return true on success; false otherwise
 606    */
 607   bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
 608   {
 609     if (key.empty() ||
 610         value.empty())
 611     {
 612       throw(Error("the key or value supplied is empty!", false));
 613     }
 614     memcached_return_t rc= memcached_replace(&memc, key.c_str(), key.length(),
 615                                            &value[0], value.size(),
 616                                            0, 0);
 617     return (rc == MEMCACHED_SUCCESS);
 618   }
 619
 620   /**
 621    * Replaces an object on the server. This method only succeeds
 622    * if the object is already present on the server. The server
 623    * to replace the object on is specified by the master_key param.
 624    *
 625    * @param[in] master_key key of server to replace object on
 626    * @param[in] key key of object to replace
 627    * @param[in[ value value to replace object with
 628    * @return true on success; false otherwise
 629    */
 630   bool replaceByKey(const std::string &master_key,
 631                     const std::string &key,
 632                     const std::vector<char> &value)
 633   {
 634     if (master_key.empty() ||
 635         key.empty() ||
 636         value.empty())
 637     {
 638       throw(Error("the master key or key supplied is empty!", false));
 639     }
 640     memcached_return_t rc= memcached_replace_by_key(&memc,
 641                                                   master_key.c_str(),
 642                                                   master_key.length(),
 643                                                   key.c_str(),
 644                                                   key.length(),
 645                                                   &value[0],
 646                                                   value.size(),
 647                                                   0, 0);
 648     return (rc == MEMCACHED_SUCCESS);
 649   }
 650
 651   /**
 652    * Places a segment of data before the last piece of data stored.
 653    *
 654    * @param[in] key key of object whose value we will prepend data to
 655    * @param[in] value data to prepend to object's value
 656    * @return true on success; false otherwise
 657    */
 658   bool prepend(const std::string &key, const std::vector<char> &value)
 659     throw(Error)
 660   {
 661     if (key.empty() || value.empty())
 662     {
 663       throw(Error("the key or value supplied is empty!", false));
 664     }
 665     memcached_return_t rc= memcached_prepend(&memc, key.c_str(), key.length(),
 666                                            &value[0], value.size(), 0, 0);
 667     return (rc == MEMCACHED_SUCCESS);
 668   }
 669
 670   /**
 671    * Places a segment of data before the last piece of data stored. The
 672    * server on which the object where we will be prepending data is stored
 673    * on is specified by the master_key parameter.
 674    *
 675    * @param[in] master_key key of server where object is stored
 676    * @param[in] key key of object whose value we will prepend data to
 677    * @param[in] value data to prepend to object's value
 678    * @return true on success; false otherwise
 679    */
 680   bool prependByKey(const std::string &master_key,
 681                     const std::string &key,
 682                     const std::vector<char> &value)
 683       throw(Error)
 684   {
 685     if (master_key.empty() ||
 686         key.empty() ||
 687         value.empty())
 688     {
 689       throw(Error("the master key or key supplied is empty!", false));
 690     }
 691     memcached_return_t rc= memcached_prepend_by_key(&memc,
 692                                                   master_key.c_str(),
 693                                                   master_key.length(),
 694                                                   key.c_str(),
 695                                                   key.length(),
 696                                                   &value[0],
 697                                                   value.size(),
 698                                                   0,
 699                                                   0);
 700     return (rc == MEMCACHED_SUCCESS);
 701   }
 702
 703   /**
 704    * Places a segment of data at the end of the last piece of data stored.
 705    *
 706    * @param[in] key key of object whose value we will append data to
 707    * @param[in] value data to append to object's value
 708    * @return true on success; false otherwise
 709    */
 710   bool append(const std::string &key, const std::vector<char> &value)
 711     throw(Error)
 712   {
 713     if (key.empty() || value.empty())
 714     {
 715       throw(Error("the key or value supplied is empty!", false));
 716     }
 717     memcached_return_t rc= memcached_append(&memc,
 718                                           key.c_str(),
 719                                           key.length(),
 720                                           &value[0],
 721                                           value.size(),
 722                                           0, 0);
 723     return (rc == MEMCACHED_SUCCESS);
 724   }
 725
 726   /**
 727    * Places a segment of data at the end of the last piece of data stored. The
 728    * server on which the object where we will be appending data is stored
 729    * on is specified by the master_key parameter.
 730    *
 731    * @param[in] master_key key of server where object is stored
 732    * @param[in] key key of object whose value we will append data to
 733    * @param[in] value data to append to object's value
 734    * @return true on success; false otherwise
 735    */
 736   bool appendByKey(const std::string &master_key,
 737                    const std::string &key,
 738                    const std::vector<char> &value)
 739     throw(Error)
 740   {
 741     if (master_key.empty() ||
 742         key.empty() ||
 743         value.empty())
 744     {
 745       throw(Error("the master key or key supplied is empty!", false));
 746     }
 747     memcached_return_t rc= memcached_append_by_key(&memc,
 748                                                  master_key.c_str(),
 749                                                  master_key.length(),
 750                                                  key.c_str(),
 751                                                  key.length(),
 752                                                  &value[0],
 753                                                  value.size(),
 754                                                  0, 0);
 755     return (rc == MEMCACHED_SUCCESS);
 756   }
 757
 758   /**
 759    * Overwrite data in the server as long as the cas_arg value
 760    * is still the same in the server.
 761    *
 762    * @param[in] key key of object in server
 763    * @param[in] value value to store for object in server
 764    * @param[in] cas_arg "cas" value
 765    */
 766   bool cas(const std::string &key,
 767            const std::vector<char> &value,
 768            uint64_t cas_arg) throw(Error)
 769   {
 770     if (key.empty() || value.empty())
 771     {
 772       throw(Error("the key or value supplied is empty!", false));
 773     }
 774     memcached_return_t rc= memcached_cas(&memc, key.c_str(), key.length(),
 775                                        &value[0], value.size(),
 776                                        0, 0, cas_arg);
 777     return (rc == MEMCACHED_SUCCESS);
 778   }
 779
 780   /**
 781    * Overwrite data in the server as long as the cas_arg value
 782    * is still the same in the server. The server to use is
 783    * specified by the master_key parameter.
 784    *
 785    * @param[in] master_key specifies server to operate on
 786    * @param[in] key key of object in server
 787    * @param[in] value value to store for object in server
 788    * @param[in] cas_arg "cas" value
 789    */
 790   bool casByKey(const std::string &master_key,
 791                 const std::string &key,
 792                 const std::vector<char> &value,
 793                 uint64_t cas_arg) throw(Error)
 794   {
 795     if (master_key.empty() ||
 796         key.empty() ||
 797         value.empty())
 798     {
 799       throw(Error("the master key, key or value supplied is empty!", false));
 800     }
 801     memcached_return_t rc= memcached_cas_by_key(&memc,
 802                                               master_key.c_str(),
 803                                               master_key.length(),
 804                                               key.c_str(),
 805                                               key.length(),
 806                                               &value[0],
 807                                               value.size(),
 808                                               0, 0, cas_arg);
 809     return (rc == MEMCACHED_SUCCESS);
 810   }
 811
 812   /**
 813    * Delete an object from the server specified by the key given.
 814    *
 815    * @param[in] key key of object to delete
 816    * @return true on success; false otherwise
 817    */
 818   bool remove(const std::string &key) throw(Error)
 819   {
 820     if (key.empty())
 821     {
 822       throw(Error("the key supplied is empty!", false));
 823     }
 824     memcached_return_t rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
 825     return (rc == MEMCACHED_SUCCESS);
 826   }
 827
 828   /**
 829    * Delete an object from the server specified by the key given.
 830    *
 831    * @param[in] key key of object to delete
 832    * @param[in] expiration time to delete the object after
 833    * @return true on success; false otherwise
 834    */
 835   bool remove(const std::string &key,
 836               time_t expiration) throw(Error)
 837   {
 838     if (key.empty())
 839     {
 840       throw(Error("the key supplied is empty!", false));
 841     }
 842     memcached_return_t rc= memcached_delete(&memc,
 843                                           key.c_str(),
 844                                           key.length(),
 845                                           expiration);
 846     return (rc == MEMCACHED_SUCCESS);
 847   }
 848
 849   /**
 850    * Delete an object from the server specified by the key given.
 851    *
 852    * @param[in] master_key specifies server to remove object from
 853    * @param[in] key key of object to delete
 854    * @return true on success; false otherwise
 855    */
 856   bool removeByKey(const std::string &master_key,
 857                    const std::string &key) throw(Error)
 858   {
 859     if (master_key.empty() || key.empty())
 860     {
 861       throw(Error("the master key or key supplied is empty!", false));
 862     }
 863     memcached_return_t rc= memcached_delete_by_key(&memc,
 864                                                  master_key.c_str(),
 865                                                  master_key.length(),
 866                                                  key.c_str(),
 867                                                  key.length(),
 868                                                  0);
 869     return (rc == MEMCACHED_SUCCESS);
 870   }
 871
 872   /**
 873    * Delete an object from the server specified by the key given.
 874    *
 875    * @param[in] master_key specifies server to remove object from
 876    * @param[in] key key of object to delete
 877    * @param[in] expiration time to delete the object after
 878    * @return true on success; false otherwise
 879    */
 880   bool removeByKey(const std::string &master_key,
 881                    const std::string &key,
 882                    time_t expiration) throw(Error)
 883   {
 884     if (master_key.empty() || key.empty())
 885     {
 886       throw(Error("the master key or key supplied is empty!", false));
 887     }
 888     memcached_return_t rc= memcached_delete_by_key(&memc,
 889                                                  master_key.c_str(),
 890                                                  master_key.length(),
 891                                                  key.c_str(),
 892                                                  key.length(),
 893                                                  expiration);
 894     return (rc == MEMCACHED_SUCCESS);
 895   }
 896
 897   /**
 898    * Wipe the contents of memcached servers.
 899    *
 900    * @param[in] expiration time to wait until wiping contents of
 901    *                       memcached servers
 902    * @return true on success; false otherwise
 903    */
 904   bool flush(time_t expiration)
 905   {
 906     memcached_return_t rc= memcached_flush(&memc, expiration);
 907     return (rc == MEMCACHED_SUCCESS);
 908   }
 909
 910   /**
 911    * Callback function for result sets. It passes the result
 912    * sets to the list of functions provided.
 913    *
 914    * @param[in] callback list of callback functions
 915    * @param[in] context pointer to memory reference that is
 916    *                    supplied to the calling function
 917    * @param[in] num_of_callbacks number of callback functions
 918    * @return true on success; false otherwise
 919    */
 920   bool fetchExecute(memcached_execute_fn *callback,
 921                     void *context,
 922                     uint32_t num_of_callbacks)
 923   {
 924     memcached_return_t rc= memcached_fetch_execute(&memc,
 925                                                  callback,
 926                                                  context,
 927                                                  num_of_callbacks);
 928     return (rc == MEMCACHED_SUCCESS);
 929   }
 930
 931   /**
 932    * Get the library version string.
 933    * @return std::string containing a copy of the library version string.
 934    */
 935   const std::string libVersion() const
 936   {
 937     const char *ver= memcached_lib_version();
 938     const std::string version(ver);
 939     return version;
 940   }
 941
 942   /**
 943    * Retrieve memcached statistics. Populate a std::map with the retrieved
 944    * stats. Each server will map to another std::map of the key:value stats.
 945    *
 946    * @param[out] stats_map a std::map to be populated with the memcached
 947    *                       stats
 948    * @return true on success; false otherwise
 949    */
 950   bool getStats(std::map< std::string, std::map<std::string, std::string> >
 951                 &stats_map)
 952   {
 953     memcached_return_t rc;
 954     memcached_stat_st *stats= memcached_stat(&memc, NULL, &rc);
 955
 956     if (rc != MEMCACHED_SUCCESS &&
 957         rc != MEMCACHED_SOME_ERRORS)
 958     {
 959       return false;
 960     }
 961
 962     uint32_t server_count= memcached_server_count(&memc);
 963
 964     /*
 965      * For each memcached server, construct a std::map for its stats and add
 966      * it to the std::map of overall stats.
 967      */
 968     for (uint32_t x= 0; x < server_count; x++)
 969     {
 970       std::ostringstream strstm;
 971       std::string server_name(memcached_server_name(&memc, servers[x]));
 972       server_name.append(":");
 973       strstm << memcached_server_port(&memc, servers[x]);
 974       server_name.append(strstm.str());
 975
 976       std::map<std::string, std::string> server_stats;
 977       char **list= NULL;
 978       char **ptr= NULL;
 979
 980       list= memcached_stat_get_keys(&memc, &stats[x], &rc);
 981       for (ptr= list; *ptr; ptr++)
 982       {
 983         char *value= memcached_stat_get_value(&memc, &stats[x], *ptr, &rc);
 984         server_stats[*ptr]= value;
 985         free(value);
 986       }
 987
 988       stats_map[server_name]= server_stats;
 989       free(list);
 990     }
 991
 992     memcached_stat_free(&memc, stats);
 993     return true;
 994   }
 995
 996 private:
 997
 998   std::string servers_list;
 999   memcached_st memc;
1000   memcached_server_st *servers;
1001   memcached_result_st result;
1002 };
1003
1004 }
1005
1006 #endif /* LIBMEMCACHEDPP_H */