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