2 * Summary: C++ interface for memcached server
4 * Copy: See Copyright for the status of this software.
6 * Authors: Padraig O'Sullivan <osullivan.padraig@gmail.com>
7 * Patrick Galbraith <patg@patg.net>
12 * @brief Libmemcached C++ interface
15 #ifndef LIBMEMCACHEDPP_H
16 #define LIBMEMCACHEDPP_H
18 #include <libmemcached/memcached.h>
19 #include <libmemcached/exception.hpp>
31 * This is the core memcached library (if later, other objects
32 * are needed, they will be created from this class).
43 memcached_create(&memc);
46 Memcache(memcached_st *clone)
51 memcached_clone(&memc, clone);
54 Memcache(const Memcache &rhs)
59 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
64 memcached_free(&memc);
68 * Get the internal memcached_st *
70 memcached_st &getImpl()
76 * Get the internal memcached_st *
78 const memcached_st &getImpl() const
84 * Return an error string for the given return structure.
86 * @param[in] rc a memcached_return structure
87 * @return error string corresponding to given return code in the library.
89 const std::string getError(memcached_return rc) const
91 /* first parameter to strerror is unused */
92 return memcached_strerror(NULL, rc);
96 * Fetches an individual value from the server. mget() must always
97 * be called before using this method.
99 * @param[in] key key of object to fetch
100 * @param[out] ret_val store returned object in this vector
101 * @return a memcached return structure
103 memcached_return fetch(std::string &key,
104 std::vector<char> &ret_val)
106 char ret_key[MEMCACHED_MAX_KEY];
107 size_t value_length= 0;
108 size_t key_length= 0;
111 char *value= memcached_fetch(&memc, ret_key, &key_length,
112 &value_length, &flags, &rc);
113 if (value && ret_val.empty())
115 ret_val.reserve(value_length);
116 ret_val.assign(value, value + value_length);
123 * Fetches an individual value from the server.
125 * @param[in] key key of object whose value to get
126 * @param[out] ret_val object that is retrieved is stored in
128 * @return true on success; false otherwise
130 bool get(const std::string &key,
131 std::vector<char> &ret_val) throw (Error)
135 size_t value_length= 0;
139 throw(Error("the key supplied is empty!", false));
141 char *value= memcached_get(&memc, key.c_str(), key.length(),
142 &value_length, &flags, &rc);
143 if (value != NULL && ret_val.empty())
145 ret_val.reserve(value_length);
146 ret_val.assign(value, value + value_length);
153 * Fetches an individual from a server which is specified by
154 * the master_key parameter that is used for determining which
155 * server an object was stored in if key partitioning was
158 * @param[in] master_key key that specifies server object is stored on
159 * @param[in] key key of object whose value to get
160 * @param[out] ret_val object that is retrieved is stored in
162 * @return true on success; false otherwise
164 bool getByKey(const std::string &master_key,
165 const std::string &key,
166 std::vector<char> &ret_val) throw(Error)
170 size_t value_length= 0;
172 if (master_key.empty() || key.empty())
174 throw(Error("the master key or key supplied is empty!", false));
176 char *value= memcached_get_by_key(&memc,
177 master_key.c_str(), master_key.length(),
178 key.c_str(), key.length(),
179 &value_length, &flags, &rc);
182 ret_val.reserve(value_length);
183 ret_val.assign(value, value + value_length);
190 * Selects multiple keys at once. This method always
191 * works asynchronously.
193 * @param[in] keys vector of keys to select
194 * @return true if all keys are found
196 bool mget(std::vector<std::string> &keys)
198 std::vector<const char *> real_keys;
199 std::vector<size_t> key_len;
201 * Construct an array which will contain the length
202 * of each of the strings in the input vector. Also, to
203 * interface with the memcached C API, we need to convert
204 * the vector of std::string's to a vector of char *.
206 real_keys.reserve(keys.size());
207 key_len.reserve(keys.size());
209 std::vector<std::string>::iterator it= keys.begin();
211 while (it != keys.end())
213 real_keys.push_back(const_cast<char *>((*it).c_str()));
214 key_len.push_back((*it).length());
219 * If the std::vector of keys is empty then we cannot
220 * call memcached_mget as we will get undefined behavior.
222 if (! real_keys.empty())
224 memcached_return rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
226 return (rc == MEMCACHED_SUCCESS);
233 * Writes an object to the server. If the object already exists, it will
234 * overwrite the existing object. This method always returns true
235 * when using non-blocking mode unless a network error occurs.
237 * @param[in] key key of object to write to server
238 * @param[in] value value of object to write to server
239 * @param[in] expiration time to keep the object stored in the server for
240 * @param[in] flags flags to store with the object
241 * @return true on succcess; false otherwise
243 bool set(const std::string &key,
244 const std::vector<char> &value,
246 uint32_t flags) throw(Error)
248 if (key.empty() || value.empty())
250 throw(Error("the key or value supplied is empty!", false));
252 memcached_return rc= memcached_set(&memc,
253 key.c_str(), key.length(),
254 &value[0], value.size(),
256 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
260 * Writes an object to a server specified by the master_key parameter.
261 * If the object already exists, it will overwrite the existing object.
263 * @param[in] master_key key that specifies server to write to
264 * @param[in] key key of object to write to server
265 * @param[in] value value of object to write to server
266 * @param[in] expiration time to keep the object stored in the server for
267 * @param[in] flags flags to store with the object
268 * @return true on succcess; false otherwise
270 bool setByKey(const std::string &master_key,
271 const std::string &key,
272 const std::vector<char> &value,
274 uint32_t flags) throw(Error)
276 if (master_key.empty() ||
280 throw(Error("the key or value supplied is empty!", false));
282 memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(),
284 key.c_str(), key.length(),
285 &value[0], value.size(),
288 return (rc == MEMCACHED_SUCCESS);
292 * Writes a list of objects to the server. Objects are specified by
293 * 2 vectors - 1 vector of keys and 1 vector of values.
295 * @param[in] keys vector of keys of objects to write to server
296 * @param[in] values vector of values of objects to write to server
297 * @param[in] expiration time to keep the objects stored in server for
298 * @param[in] flags flags to store with the objects
299 * @return true on success; false otherwise
301 bool setAll(std::vector<std::string> &keys,
302 std::vector< std::vector<char> *> &values,
304 uint32_t flags) throw(Error)
306 if (keys.size() != values.size())
308 throw(Error("The number of keys and values do not match!", false));
311 std::vector<std::string>::iterator key_it= keys.begin();
312 std::vector< std::vector<char> *>::iterator val_it= values.begin();
313 while (key_it != keys.end())
315 retval= set((*key_it), *(*val_it), expiration, flags);
327 * Writes a list of objects to the server. Objects are specified by
328 * a map of keys to values.
330 * @param[in] key_value_map map of keys and values to store in server
331 * @param[in] expiration time to keep the objects stored in server for
332 * @param[in] flags flags to store with the objects
333 * @return true on success; false otherwise
335 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
337 uint32_t flags) throw(Error)
339 if (key_value_map.empty())
341 throw(Error("The key/values are not properly set!", false));
344 std::map<const std::string, std::vector<char> >::iterator it=
345 key_value_map.begin();
346 while (it != key_value_map.end())
348 retval= set(it->first, it->second, expiration, flags);
352 sprintf(err_buff, "There was an error setting the key %s",
354 throw(Error(err_buff, false));
362 * Increment the value of the object associated with the specified
363 * key by the offset given. The resulting value is saved in the value
366 * @param[in] key key of object in server whose value to increment
367 * @param[in] offset amount to increment object's value by
368 * @param[out] value store the result of the increment here
369 * @return true on success; false otherwise
371 bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
375 throw(Error("the key supplied is empty!", false));
377 memcached_return rc= memcached_increment(&memc, key.c_str(), key.length(),
379 return (rc == MEMCACHED_SUCCESS);
383 * Decrement the value of the object associated with the specified
384 * key by the offset given. The resulting value is saved in the value
387 * @param[in] key key of object in server whose value to decrement
388 * @param[in] offset amount to increment object's value by
389 * @param[out] value store the result of the decrement here
390 * @return true on success; false otherwise
392 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
397 throw(Error("the key supplied is empty!", false));
399 memcached_return rc= memcached_decrement(&memc, key.c_str(),
402 return (rc == MEMCACHED_SUCCESS);
407 * Add an object with the specified key and value to the server. This
408 * function returns false if the object already exists on the server.
410 * @param[in] key key of object to add
411 * @param[in] value of object to add
412 * @return true on success; false otherwise
414 bool add(const std::string &key, const std::vector<char> &value)
417 if (key.empty() || value.empty())
419 throw(Error("the key or value supplied is empty!", false));
421 memcached_return rc= memcached_add(&memc, key.c_str(), key.length(),
422 &value[0], value.size(), 0, 0);
423 return (rc == MEMCACHED_SUCCESS);
427 * Add an object with the specified key and value to the server. This
428 * function returns false if the object already exists on the server. The
429 * server to add the object to is specified by the master_key parameter.
431 * @param[in[ master_key key of server to add object to
432 * @param[in] key key of object to add
433 * @param[in] value of object to add
434 * @return true on success; false otherwise
436 bool addByKey(const std::string &master_key,
437 const std::string &key,
438 const std::vector<char> &value) throw(Error)
440 if (master_key.empty() ||
444 throw(Error("the master key or key supplied is empty!", false));
446 memcached_return rc= memcached_add_by_key(&memc,
454 return (rc == MEMCACHED_SUCCESS);
458 * Replaces an object on the server. This method only succeeds
459 * if the object is already present on the server.
461 * @param[in] key key of object to replace
462 * @param[in[ value value to replace object with
463 * @return true on success; false otherwise
465 bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
470 throw(Error("the key or value supplied is empty!", false));
472 memcached_return rc= memcached_replace(&memc, key.c_str(), key.length(),
473 &value[0], value.size(),
475 return (rc == MEMCACHED_SUCCESS);
479 * Replaces an object on the server. This method only succeeds
480 * if the object is already present on the server. The server
481 * to replace the object on is specified by the master_key param.
483 * @param[in] master_key key of server to replace object on
484 * @param[in] key key of object to replace
485 * @param[in[ value value to replace object with
486 * @return true on success; false otherwise
488 bool replaceByKey(const std::string &master_key,
489 const std::string &key,
490 const std::vector<char> &value)
492 if (master_key.empty() ||
496 throw(Error("the master key or key supplied is empty!", false));
498 memcached_return rc= memcached_replace_by_key(&memc,
506 return (rc == MEMCACHED_SUCCESS);
510 * Places a segment of data before the last piece of data stored.
512 * @param[in] key key of object whose value we will prepend data to
513 * @param[in] value data to prepend to object's value
514 * @return true on success; false otherwise
516 bool prepend(const std::string &key, const std::vector<char> &value)
519 if (key.empty() || value.empty())
521 throw(Error("the key or value supplied is empty!", false));
523 memcached_return rc= memcached_prepend(&memc, key.c_str(), key.length(),
524 &value[0], value.size(), 0, 0);
525 return (rc == MEMCACHED_SUCCESS);
529 * Places a segment of data before the last piece of data stored. The
530 * server on which the object where we will be prepending data is stored
531 * on is specified by the master_key parameter.
533 * @param[in] master_key key of server where object is stored
534 * @param[in] key key of object whose value we will prepend data to
535 * @param[in] value data to prepend to object's value
536 * @return true on success; false otherwise
538 bool prependByKey(const std::string &master_key,
539 const std::string &key,
540 const std::vector<char> &value)
543 if (master_key.empty() ||
547 throw(Error("the master key or key supplied is empty!", false));
549 memcached_return rc= memcached_prepend_by_key(&memc,
558 return (rc == MEMCACHED_SUCCESS);
562 * Places a segment of data at the end of the last piece of data stored.
564 * @param[in] key key of object whose value we will append data to
565 * @param[in] value data to append to object's value
566 * @return true on success; false otherwise
568 bool append(const std::string &key, const std::vector<char> &value)
571 if (key.empty() || value.empty())
573 throw(Error("the key or value supplied is empty!", false));
575 memcached_return rc= memcached_append(&memc,
581 return (rc == MEMCACHED_SUCCESS);
585 * Places a segment of data at the end of the last piece of data stored. The
586 * server on which the object where we will be appending data is stored
587 * on is specified by the master_key parameter.
589 * @param[in] master_key key of server where object is stored
590 * @param[in] key key of object whose value we will append data to
591 * @param[in] value data to append to object's value
592 * @return true on success; false otherwise
594 bool appendByKey(const std::string &master_key,
595 const std::string &key,
596 const std::vector<char> &value)
599 if (master_key.empty() ||
603 throw(Error("the master key or key supplied is empty!", false));
605 memcached_return rc= memcached_append_by_key(&memc,
613 return (rc == MEMCACHED_SUCCESS);
617 * Overwrite data in the server as long as the cas_arg value
618 * is still the same in the server.
620 * @param[in] key key of object in server
621 * @param[in] value value to store for object in server
622 * @param[in] cas_arg "cas" value
624 bool cas(const std::string &key,
625 const std::vector<char> &value,
626 uint64_t cas_arg) throw(Error)
628 if (key.empty() || value.empty())
630 throw(Error("the key or value supplied is empty!", false));
632 memcached_return rc= memcached_cas(&memc, key.c_str(), key.length(),
633 &value[0], value.size(),
635 return (rc == MEMCACHED_SUCCESS);
639 * Overwrite data in the server as long as the cas_arg value
640 * is still the same in the server. The server to use is
641 * specified by the master_key parameter.
643 * @param[in] master_key specifies server to operate on
644 * @param[in] key key of object in server
645 * @param[in] value value to store for object in server
646 * @param[in] cas_arg "cas" value
648 bool casByKey(const std::string &master_key,
649 const std::string &key,
650 const std::vector<char> &value,
651 uint64_t cas_arg) throw(Error)
653 if (master_key.empty() ||
657 throw(Error("the master key, key or value supplied is empty!", false));
659 memcached_return rc= memcached_cas_by_key(&memc,
667 return (rc == MEMCACHED_SUCCESS);
671 * Delete an object from the server specified by the key given.
673 * @param[in] key key of object to delete
674 * @return true on success; false otherwise
676 bool remove(const std::string &key) throw(Error)
680 throw(Error("the key supplied is empty!", false));
682 memcached_return rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
683 return (rc == MEMCACHED_SUCCESS);
687 * Delete an object from the server specified by the key given.
689 * @param[in] key key of object to delete
690 * @param[in] expiration time to delete the object after
691 * @return true on success; false otherwise
693 bool remove(const std::string &key,
694 time_t expiration) throw(Error)
698 throw(Error("the key supplied is empty!", false));
700 memcached_return rc= memcached_delete(&memc,
704 return (rc == MEMCACHED_SUCCESS);
708 * Delete an object from the server specified by the key given.
710 * @param[in] master_key specifies server to remove object from
711 * @param[in] key key of object to delete
712 * @return true on success; false otherwise
714 bool removeByKey(const std::string &master_key,
715 const std::string &key) throw(Error)
717 if (master_key.empty() || key.empty())
719 throw(Error("the master key or key supplied is empty!", false));
721 memcached_return rc= memcached_delete_by_key(&memc,
727 return (rc == MEMCACHED_SUCCESS);
731 * Delete an object from the server specified by the key given.
733 * @param[in] master_key specifies server to remove object from
734 * @param[in] key key of object to delete
735 * @param[in] expiration time to delete the object after
736 * @return true on success; false otherwise
738 bool removeByKey(const std::string &master_key,
739 const std::string &key,
740 time_t expiration) throw(Error)
742 if (master_key.empty() || key.empty())
744 throw(Error("the master key or key supplied is empty!", false));
746 memcached_return rc= memcached_delete_by_key(&memc,
752 return (rc == MEMCACHED_SUCCESS);
756 * Wipe the contents of memcached servers.
758 * @param[in] expiration time to wait until wiping contents of
760 * @return true on success; false otherwise
762 bool flush(time_t expiration)
764 memcached_return rc= memcached_flush(&memc, expiration);
765 return (rc == MEMCACHED_SUCCESS);
769 * Callback function for result sets. It passes the result
770 * sets to the list of functions provided.
772 * @param[in] callback list of callback functions
773 * @param[in] context pointer to memory reference that is
774 * supplied to the calling function
775 * @param[in] num_of_callbacks number of callback functions
776 * @return true on success; false otherwise
778 bool fetchExecute(memcached_execute_function *callback,
780 unsigned int num_of_callbacks)
782 memcached_return rc= memcached_fetch_execute(&memc,
786 return (rc == MEMCACHED_SUCCESS);
790 * Get the library version string.
791 * @return std::string containing a copy of the library version string.
793 const std::string libVersion() const
795 const char *ver= memcached_lib_version();
796 const std::string version(ver);
803 memcached_result_st result;
808 #endif /* LIBMEMCACHEDPP_H */