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       return true;
 307     }
 308     return false;
 309   }
 310
 311   /**
 312    * Selects multiple keys at once. This method always
 313    * works asynchronously.
 314    *
 315    * @param[in] keys vector of keys to select
 316    * @return true if all keys are found
 317    */
 318   bool mget(std::vector<std::string> &keys)
 319   {
 320     std::vector<const char *> real_keys;
 321     std::vector<size_t> key_len;
 322     /*
 323      * Construct an array which will contain the length
 324      * of each of the strings in the input vector. Also, to
 325      * interface with the memcached C API, we need to convert
 326      * the vector of std::string's to a vector of char *.
 327      */
 328     real_keys.reserve(keys.size());
 329     key_len.reserve(keys.size());
 330
 331     std::vector<std::string>::iterator it= keys.begin();
 332
 333     while (it != keys.end())
 334     {
 335       real_keys.push_back(const_cast<char *>((*it).c_str()));
 336       key_len.push_back((*it).length());
 337       ++it;
 338     }
 339
 340     /*
 341      * If the std::vector of keys is empty then we cannot
 342      * call memcached_mget as we will get undefined behavior.
 343      */
 344     if (! real_keys.empty())
 345     {
 346       memcached_return rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
 347                                           real_keys.size());
 348       return (rc == MEMCACHED_SUCCESS);
 349     }
 350
 351     return false;
 352   }
 353
 354   /**
 355    * Writes an object to the server. If the object already exists, it will
 356    * overwrite the existing object. This method always returns true
 357    * when using non-blocking mode unless a network error occurs.
 358    *
 359    * @param[in] key key of object to write to server
 360    * @param[in] value value of object to write to server
 361    * @param[in] expiration time to keep the object stored in the server for
 362    * @param[in] flags flags to store with the object
 363    * @return true on succcess; false otherwise
 364    */
 365   bool set(const std::string &key,
 366            const std::vector<char> &value,
 367            time_t expiration,
 368            uint32_t flags) throw(Error)
 369   {
 370     if (key.empty() || value.empty())
 371     {
 372       throw(Error("the key or value supplied is empty!", false));
 373     }
 374     memcached_return rc= memcached_set(&memc,
 375                                        key.c_str(), key.length(),
 376                                        &value[0], value.size(),
 377                                        expiration, flags);
 378     return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
 379   }
 380
 381   /**
 382    * Writes an object to a server specified by the master_key parameter.
 383    * If the object already exists, it will overwrite the existing object.
 384    *
 385    * @param[in] master_key key that specifies server to write to
 386    * @param[in] key key of object to write to server
 387    * @param[in] value value of object to write to server
 388    * @param[in] expiration time to keep the object stored in the server for
 389    * @param[in] flags flags to store with the object
 390    * @return true on succcess; false otherwise
 391    */
 392   bool setByKey(const std::string &master_key,
 393                 const std::string &key,
 394                 const std::vector<char> &value,
 395                 time_t expiration,
 396                 uint32_t flags) throw(Error)
 397   {
 398     if (master_key.empty() ||
 399         key.empty() ||
 400         value.empty())
 401     {
 402       throw(Error("the key or value supplied is empty!", false));
 403     }
 404     memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(),
 405                                               master_key.length(),
 406                                               key.c_str(), key.length(),
 407                                               &value[0], value.size(),
 408                                               expiration,
 409                                               flags);
 410     return (rc == MEMCACHED_SUCCESS);
 411   }
 412
 413   /**
 414    * Writes a list of objects to the server. Objects are specified by
 415    * 2 vectors - 1 vector of keys and 1 vector of values.
 416    *
 417    * @param[in] keys vector of keys of objects to write to server
 418    * @param[in] values vector of values of objects to write to server
 419    * @param[in] expiration time to keep the objects stored in server for
 420    * @param[in] flags flags to store with the objects
 421    * @return true on success; false otherwise
 422    */
 423   bool setAll(std::vector<std::string> &keys,
 424               std::vector< std::vector<char> *> &values,
 425               time_t expiration,
 426               uint32_t flags) throw(Error)
 427   {
 428     if (keys.size() != values.size())
 429     {
 430       throw(Error("The number of keys and values do not match!", false));
 431     }
 432     bool retval= true;
 433     std::vector<std::string>::iterator key_it= keys.begin();
 434     std::vector< std::vector<char> *>::iterator val_it= values.begin();
 435     while (key_it != keys.end())
 436     {
 437       retval= set((*key_it), *(*val_it), expiration, flags);
 438       if (retval == false)
 439       {
 440         return retval;
 441       }
 442       ++key_it;
 443       ++val_it;
 444     }
 445     return retval;
 446   }
 447
 448   /**
 449    * Writes a list of objects to the server. Objects are specified by
 450    * a map of keys to values.
 451    *
 452    * @param[in] key_value_map map of keys and values to store in server
 453    * @param[in] expiration time to keep the objects stored in server for
 454    * @param[in] flags flags to store with the objects
 455    * @return true on success; false otherwise
 456    */
 457   bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
 458               time_t expiration,
 459               uint32_t flags) throw(Error)
 460   {
 461     if (key_value_map.empty())
 462     {
 463       throw(Error("The key/values are not properly set!", false));
 464     }
 465     bool retval= true;
 466     std::map<const std::string, std::vector<char> >::iterator it=
 467       key_value_map.begin();
 468     while (it != key_value_map.end())
 469     {
 470       retval= set(it->first, it->second, expiration, flags);
 471       if (retval == false)
 472       {
 473         std::string err_buff("There was an error setting the key ");
 474         err_buff.append(it->first);
 475         throw(Error(err_buff, false));
 476       }
 477       ++it;
 478     }
 479     return true;
 480   }
 481
 482   /**
 483    * Increment the value of the object associated with the specified
 484    * key by the offset given. The resulting value is saved in the value
 485    * parameter.
 486    *
 487    * @param[in] key key of object in server whose value to increment
 488    * @param[in] offset amount to increment object's value by
 489    * @param[out] value store the result of the increment here
 490    * @return true on success; false otherwise
 491    */
 492   bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
 493   {
 494     if (key.empty())
 495     {
 496       throw(Error("the key supplied is empty!", false));
 497     }
 498     memcached_return rc= memcached_increment(&memc, key.c_str(), key.length(),
 499                                              offset, value);
 500     return (rc == MEMCACHED_SUCCESS);
 501   }
 502
 503   /**
 504    * Decrement 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 decrement
 509    * @param[in] offset amount to increment object's value by
 510    * @param[out] value store the result of the decrement here
 511    * @return true on success; false otherwise
 512    */
 513   bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
 514     throw(Error)
 515   {
 516     if (key.empty())
 517     {
 518       throw(Error("the key supplied is empty!", false));
 519     }
 520     memcached_return rc= memcached_decrement(&memc, key.c_str(),
 521                                              key.length(),
 522                                              offset, value);
 523     return (rc == MEMCACHED_SUCCESS);
 524   }
 525
 526
 527   /**
 528    * Add an object with the specified key and value to the server. This
 529    * function returns false if the object already exists on the server.
 530    *
 531    * @param[in] key key of object to add
 532    * @param[in] value of object to add
 533    * @return true on success; false otherwise
 534    */
 535   bool add(const std::string &key, const std::vector<char> &value)
 536     throw(Error)
 537   {
 538     if (key.empty() || value.empty())
 539     {
 540       throw(Error("the key or value supplied is empty!", false));
 541     }
 542     memcached_return rc= memcached_add(&memc, key.c_str(), key.length(),
 543                                        &value[0], value.size(), 0, 0);
 544     return (rc == MEMCACHED_SUCCESS);
 545   }
 546
 547   /**
 548    * Add an object with the specified key and value to the server. This
 549    * function returns false if the object already exists on the server. The
 550    * server to add the object to is specified by the master_key parameter.
 551    *
 552    * @param[in[ master_key key of server to add object to
 553    * @param[in] key key of object to add
 554    * @param[in] value of object to add
 555    * @return true on success; false otherwise
 556    */
 557   bool addByKey(const std::string &master_key,
 558                 const std::string &key,
 559                 const std::vector<char> &value) throw(Error)
 560   {
 561     if (master_key.empty() ||
 562         key.empty() ||
 563         value.empty())
 564     {
 565       throw(Error("the master key or key supplied is empty!", false));
 566     }
 567     memcached_return rc= memcached_add_by_key(&memc,
 568                                               master_key.c_str(),
 569                                               master_key.length(),
 570                                               key.c_str(),
 571                                               key.length(),
 572                                               &value[0],
 573                                               value.size(),
 574                                               0, 0);
 575     return (rc == MEMCACHED_SUCCESS);
 576   }
 577
 578   /**
 579    * Replaces an object on the server. This method only succeeds
 580    * if the object is already present on the server.
 581    *
 582    * @param[in] key key of object to replace
 583    * @param[in[ value value to replace object with
 584    * @return true on success; false otherwise
 585    */
 586   bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
 587   {
 588     if (key.empty() ||
 589         value.empty())
 590     {
 591       throw(Error("the key or value supplied is empty!", false));
 592     }
 593     memcached_return rc= memcached_replace(&memc, key.c_str(), key.length(),
 594                                            &value[0], 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. The server
 602    * to replace the object on is specified by the master_key param.
 603    *
 604    * @param[in] master_key key of server to replace object on
 605    * @param[in] key key of object to replace
 606    * @param[in[ value value to replace object with
 607    * @return true on success; false otherwise
 608    */
 609   bool replaceByKey(const std::string &master_key,
 610                     const std::string &key,
 611                     const std::vector<char> &value)
 612   {
 613     if (master_key.empty() ||
 614         key.empty() ||
 615         value.empty())
 616     {
 617       throw(Error("the master key or key supplied is empty!", false));
 618     }
 619     memcached_return rc= memcached_replace_by_key(&memc,
 620                                                   master_key.c_str(),
 621                                                   master_key.length(),
 622                                                   key.c_str(),
 623                                                   key.length(),
 624                                                   &value[0],
 625                                                   value.size(),
 626                                                   0, 0);
 627     return (rc == MEMCACHED_SUCCESS);
 628   }
 629
 630   /**
 631    * Places a segment of data before the last piece of data stored.
 632    *
 633    * @param[in] key key of object whose value we will prepend data to
 634    * @param[in] value data to prepend to object's value
 635    * @return true on success; false otherwise
 636    */
 637   bool prepend(const std::string &key, const std::vector<char> &value)
 638     throw(Error)
 639   {
 640     if (key.empty() || value.empty())
 641     {
 642       throw(Error("the key or value supplied is empty!", false));
 643     }
 644     memcached_return rc= memcached_prepend(&memc, key.c_str(), key.length(),
 645                                            &value[0], value.size(), 0, 0);
 646     return (rc == MEMCACHED_SUCCESS);
 647   }
 648
 649   /**
 650    * Places a segment of data before the last piece of data stored. The
 651    * server on which the object where we will be prepending data is stored
 652    * on is specified by the master_key parameter.
 653    *
 654    * @param[in] master_key key of server where object is stored
 655    * @param[in] key key of object whose value we will prepend data to
 656    * @param[in] value data to prepend to object's value
 657    * @return true on success; false otherwise
 658    */
 659   bool prependByKey(const std::string &master_key,
 660                     const std::string &key,
 661                     const std::vector<char> &value)
 662       throw(Error)
 663   {
 664     if (master_key.empty() ||
 665         key.empty() ||
 666         value.empty())
 667     {
 668       throw(Error("the master key or key supplied is empty!", false));
 669     }
 670     memcached_return rc= memcached_prepend_by_key(&memc,
 671                                                   master_key.c_str(),
 672                                                   master_key.length(),
 673                                                   key.c_str(),
 674                                                   key.length(),
 675                                                   &value[0],
 676                                                   value.size(),
 677                                                   0,
 678                                                   0);
 679     return (rc == MEMCACHED_SUCCESS);
 680   }
 681
 682   /**
 683    * Places a segment of data at the end of the last piece of data stored.
 684    *
 685    * @param[in] key key of object whose value we will append data to
 686    * @param[in] value data to append to object's value
 687    * @return true on success; false otherwise
 688    */
 689   bool append(const std::string &key, const std::vector<char> &value)
 690     throw(Error)
 691   {
 692     if (key.empty() || value.empty())
 693     {
 694       throw(Error("the key or value supplied is empty!", false));
 695     }
 696     memcached_return rc= memcached_append(&memc,
 697                                           key.c_str(),
 698                                           key.length(),
 699                                           &value[0],
 700                                           value.size(),
 701                                           0, 0);
 702     return (rc == MEMCACHED_SUCCESS);
 703   }
 704
 705   /**
 706    * Places a segment of data at the end of the last piece of data stored. The
 707    * server on which the object where we will be appending data is stored
 708    * on is specified by the master_key parameter.
 709    *
 710    * @param[in] master_key key of server where object is stored
 711    * @param[in] key key of object whose value we will append data to
 712    * @param[in] value data to append to object's value
 713    * @return true on success; false otherwise
 714    */
 715   bool appendByKey(const std::string &master_key,
 716                    const std::string &key,
 717                    const std::vector<char> &value)
 718     throw(Error)
 719   {
 720     if (master_key.empty() ||
 721         key.empty() ||
 722         value.empty())
 723     {
 724       throw(Error("the master key or key supplied is empty!", false));
 725     }
 726     memcached_return rc= memcached_append_by_key(&memc,
 727                                                  master_key.c_str(),
 728                                                  master_key.length(),
 729                                                  key.c_str(),
 730                                                  key.length(),
 731                                                  &value[0],
 732                                                  value.size(),
 733                                                  0, 0);
 734     return (rc == MEMCACHED_SUCCESS);
 735   }
 736
 737   /**
 738    * Overwrite data in the server as long as the cas_arg value
 739    * is still the same in the server.
 740    *
 741    * @param[in] key key of object in server
 742    * @param[in] value value to store for object in server
 743    * @param[in] cas_arg "cas" value
 744    */
 745   bool cas(const std::string &key,
 746            const std::vector<char> &value,
 747            uint64_t cas_arg) throw(Error)
 748   {
 749     if (key.empty() || value.empty())
 750     {
 751       throw(Error("the key or value supplied is empty!", false));
 752     }
 753     memcached_return rc= memcached_cas(&memc, key.c_str(), key.length(),
 754                                        &value[0], value.size(),
 755                                        0, 0, cas_arg);
 756     return (rc == MEMCACHED_SUCCESS);
 757   }
 758
 759   /**
 760    * Overwrite data in the server as long as the cas_arg value
 761    * is still the same in the server. The server to use is
 762    * specified by the master_key parameter.
 763    *
 764    * @param[in] master_key specifies server to operate on
 765    * @param[in] key key of object in server
 766    * @param[in] value value to store for object in server
 767    * @param[in] cas_arg "cas" value
 768    */
 769   bool casByKey(const std::string &master_key,
 770                 const std::string &key,
 771                 const std::vector<char> &value,
 772                 uint64_t cas_arg) throw(Error)
 773   {
 774     if (master_key.empty() ||
 775         key.empty() ||
 776         value.empty())
 777     {
 778       throw(Error("the master key, key or value supplied is empty!", false));
 779     }
 780     memcached_return rc= memcached_cas_by_key(&memc,
 781                                               master_key.c_str(),
 782                                               master_key.length(),
 783                                               key.c_str(),
 784                                               key.length(),
 785                                               &value[0],
 786                                               value.size(),
 787                                               0, 0, cas_arg);
 788     return (rc == MEMCACHED_SUCCESS);
 789   }
 790
 791   /**
 792    * Delete an object from the server specified by the key given.
 793    *
 794    * @param[in] key key of object to delete
 795    * @return true on success; false otherwise
 796    */
 797   bool remove(const std::string &key) throw(Error)
 798   {
 799     if (key.empty())
 800     {
 801       throw(Error("the key supplied is empty!", false));
 802     }
 803     memcached_return rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
 804     return (rc == MEMCACHED_SUCCESS);
 805   }
 806
 807   /**
 808    * Delete an object from the server specified by the key given.
 809    *
 810    * @param[in] key key of object to delete
 811    * @param[in] expiration time to delete the object after
 812    * @return true on success; false otherwise
 813    */
 814   bool remove(const std::string &key,
 815               time_t expiration) throw(Error)
 816   {
 817     if (key.empty())
 818     {
 819       throw(Error("the key supplied is empty!", false));
 820     }
 821     memcached_return rc= memcached_delete(&memc,
 822                                           key.c_str(),
 823                                           key.length(),
 824                                           expiration);
 825     return (rc == MEMCACHED_SUCCESS);
 826   }
 827
 828   /**
 829    * Delete an object from the server specified by the key given.
 830    *
 831    * @param[in] master_key specifies server to remove object from
 832    * @param[in] key key of object to delete
 833    * @return true on success; false otherwise
 834    */
 835   bool removeByKey(const std::string &master_key,
 836                    const std::string &key) throw(Error)
 837   {
 838     if (master_key.empty() || key.empty())
 839     {
 840       throw(Error("the master key or key supplied is empty!", false));
 841     }
 842     memcached_return rc= memcached_delete_by_key(&memc,
 843                                                  master_key.c_str(),
 844                                                  master_key.length(),
 845                                                  key.c_str(),
 846                                                  key.length(),
 847                                                  0);
 848     return (rc == MEMCACHED_SUCCESS);
 849   }
 850
 851   /**
 852    * Delete an object from the server specified by the key given.
 853    *
 854    * @param[in] master_key specifies server to remove object from
 855    * @param[in] key key of object to delete
 856    * @param[in] expiration time to delete the object after
 857    * @return true on success; false otherwise
 858    */
 859   bool removeByKey(const std::string &master_key,
 860                    const std::string &key,
 861                    time_t expiration) throw(Error)
 862   {
 863     if (master_key.empty() || key.empty())
 864     {
 865       throw(Error("the master key or key supplied is empty!", false));
 866     }
 867     memcached_return rc= memcached_delete_by_key(&memc,
 868                                                  master_key.c_str(),
 869                                                  master_key.length(),
 870                                                  key.c_str(),
 871                                                  key.length(),
 872                                                  expiration);
 873     return (rc == MEMCACHED_SUCCESS);
 874   }
 875
 876   /**
 877    * Wipe the contents of memcached servers.
 878    *
 879    * @param[in] expiration time to wait until wiping contents of
 880    *                       memcached servers
 881    * @return true on success; false otherwise
 882    */
 883   bool flush(time_t expiration)
 884   {
 885     memcached_return rc= memcached_flush(&memc, expiration);
 886     return (rc == MEMCACHED_SUCCESS);
 887   }
 888
 889   /**
 890    * Callback function for result sets. It passes the result
 891    * sets to the list of functions provided.
 892    *
 893    * @param[in] callback list of callback functions
 894    * @param[in] context pointer to memory reference that is
 895    *                    supplied to the calling function
 896    * @param[in] num_of_callbacks number of callback functions
 897    * @return true on success; false otherwise
 898    */
 899   bool fetchExecute(memcached_execute_function *callback,
 900                     void *context,
 901                     unsigned int num_of_callbacks)
 902   {
 903     memcached_return rc= memcached_fetch_execute(&memc,
 904                                                  callback,
 905                                                  context,
 906                                                  num_of_callbacks);
 907     return (rc == MEMCACHED_SUCCESS);
 908   }
 909
 910   /**
 911    * Get the library version string.
 912    * @return std::string containing a copy of the library version string.
 913    */
 914   const std::string libVersion() const
 915   {
 916     const char *ver= memcached_lib_version();
 917     const std::string version(ver);
 918     return version;
 919   }
 920
 921 private:
 922
 923   std::string servers_list;
 924   memcached_st memc;
 925   memcached_server_st *servers;
 926   memcached_result_st result;
 927 };
 928
 929 }
 930
 931 #endif /* LIBMEMCACHEDPP_H */