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>
32 * This is the core memcached library (if later, other objects
33 * are needed, they will be created from this class).
46 memcached_create(&memc);
49 Memcache(const std::string &in_servers_list)
51 servers_list(in_servers_list),
56 memcached_create(&memc);
57 servers= memcached_servers_parse(servers_list.c_str());
58 memcached_server_push(&memc, servers);
61 Memcache(const std::string &hostname,
69 memcached_create(&memc);
70 servers_list.append(hostname);
71 servers_list.append(":");
72 std::ostringstream strsmt;
74 servers_list.append(strsmt.str());
75 servers= memcached_servers_parse(servers_list.c_str());
76 memcached_server_push(&memc, servers);
79 Memcache(memcached_st *clone)
86 memcached_clone(&memc, clone);
89 Memcache(const Memcache &rhs)
91 servers_list(rhs.servers_list),
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);
101 Memcache &operator=(const Memcache &rhs)
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);
114 memcached_free(&memc);
115 memcached_server_list_free(servers);
119 * Get the internal memcached_st *
121 memcached_st &getImpl()
127 * Get the internal memcached_st *
129 const memcached_st &getImpl() const
135 * Return an error string for the given return structure.
137 * @param[in] rc a memcached_return structure
138 * @return error string corresponding to given return code in the library.
140 const std::string getError(memcached_return rc) const
142 /* first parameter to strerror is unused */
143 return memcached_strerror(NULL, rc);
147 * Return the string which contains the list of memcached servers being
150 * @return a std::string containing the list of memcached servers
152 const std::string getServersList() const
158 * Set the list of memcached servers to use.
160 * @param[in] in_servers_list list of servers
161 * @return true on success; false otherwise
163 bool setServers(const std::string &in_servers_list)
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);
172 * Add a server to the list of memcached servers to use.
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
178 bool addServer(const std::string &server_name, unsigned int port)
181 std::ostringstream strstm;
182 servers_list.append(",");
183 servers_list.append(server_name);
184 servers_list.append(":");
186 servers_list.append(strstm.str());
187 servers= memcached_server_list_append(servers,
191 memcached_server_push(&memc, servers);
192 return (rc == MEMCACHED_SUCCESS);
196 * Remove a server from the list of memcached servers to use.
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
202 bool removeServer(const std::string &server_name, size_t port)
205 std::ostringstream strstm;
207 tmp_str.append(server_name);
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);
217 * Fetches an individual value from the server. mget() must always
218 * be called before using this method.
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
224 memcached_return fetch(std::string &key,
225 std::vector<char> &ret_val)
227 char ret_key[MEMCACHED_MAX_KEY];
228 size_t value_length= 0;
229 size_t key_length= 0;
232 char *value= memcached_fetch(&memc, ret_key, &key_length,
233 &value_length, &flags, &rc);
234 if (value && ret_val.empty())
236 ret_val.reserve(value_length);
237 ret_val.assign(value, value + value_length);
244 * Fetches an individual value from the server.
246 * @param[in] key key of object whose value to get
247 * @param[out] ret_val object that is retrieved is stored in
249 * @return true on success; false otherwise
251 bool get(const std::string &key,
252 std::vector<char> &ret_val) throw (Error)
256 size_t value_length= 0;
260 throw(Error("the key supplied is empty!", false));
262 char *value= memcached_get(&memc, key.c_str(), key.length(),
263 &value_length, &flags, &rc);
264 if (value != NULL && ret_val.empty())
266 ret_val.reserve(value_length);
267 ret_val.assign(value, value + value_length);
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
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
284 * @return true on success; false otherwise
286 bool getByKey(const std::string &master_key,
287 const std::string &key,
288 std::vector<char> &ret_val) throw(Error)
292 size_t value_length= 0;
294 if (master_key.empty() || key.empty())
296 throw(Error("the master key or key supplied is empty!", false));
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);
304 ret_val.reserve(value_length);
305 ret_val.assign(value, value + value_length);
313 * Selects multiple keys at once. This method always
314 * works asynchronously.
316 * @param[in] keys vector of keys to select
317 * @return true if all keys are found
319 bool mget(std::vector<std::string> &keys)
321 std::vector<const char *> real_keys;
322 std::vector<size_t> key_len;
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 *.
329 real_keys.reserve(keys.size());
330 key_len.reserve(keys.size());
332 std::vector<std::string>::iterator it= keys.begin();
334 while (it != keys.end())
336 real_keys.push_back(const_cast<char *>((*it).c_str()));
337 key_len.push_back((*it).length());
342 * If the std::vector of keys is empty then we cannot
343 * call memcached_mget as we will get undefined behavior.
345 if (! real_keys.empty())
347 memcached_return rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
349 return (rc == MEMCACHED_SUCCESS);
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.
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
366 bool set(const std::string &key,
367 const std::vector<char> &value,
369 uint32_t flags) throw(Error)
371 if (key.empty() || value.empty())
373 throw(Error("the key or value supplied is empty!", false));
375 memcached_return rc= memcached_set(&memc,
376 key.c_str(), key.length(),
377 &value[0], value.size(),
379 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
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.
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
393 bool setByKey(const std::string &master_key,
394 const std::string &key,
395 const std::vector<char> &value,
397 uint32_t flags) throw(Error)
399 if (master_key.empty() ||
403 throw(Error("the key or value supplied is empty!", false));
405 memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(),
407 key.c_str(), key.length(),
408 &value[0], value.size(),
411 return (rc == MEMCACHED_SUCCESS);
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.
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
424 bool setAll(std::vector<std::string> &keys,
425 std::vector< std::vector<char> *> &values,
427 uint32_t flags) throw(Error)
429 if (keys.size() != values.size())
431 throw(Error("The number of keys and values do not match!", false));
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())
438 retval= set((*key_it), *(*val_it), expiration, flags);
450 * Writes a list of objects to the server. Objects are specified by
451 * a map of keys to values.
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
458 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
460 uint32_t flags) throw(Error)
462 if (key_value_map.empty())
464 throw(Error("The key/values are not properly set!", false));
467 std::map<const std::string, std::vector<char> >::iterator it=
468 key_value_map.begin();
469 while (it != key_value_map.end())
471 retval= set(it->first, it->second, expiration, flags);
474 std::string err_buff("There was an error setting the key ");
475 err_buff.append(it->first);
476 throw(Error(err_buff, false));
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
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
493 bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
497 throw(Error("the key supplied is empty!", false));
499 memcached_return rc= memcached_increment(&memc, key.c_str(), key.length(),
501 return (rc == MEMCACHED_SUCCESS);
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
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
514 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
519 throw(Error("the key supplied is empty!", false));
521 memcached_return rc= memcached_decrement(&memc, key.c_str(),
524 return (rc == MEMCACHED_SUCCESS);
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.
532 * @param[in] key key of object to add
533 * @param[in] value of object to add
534 * @return true on success; false otherwise
536 bool add(const std::string &key, const std::vector<char> &value)
539 if (key.empty() || value.empty())
541 throw(Error("the key or value supplied is empty!", false));
543 memcached_return rc= memcached_add(&memc, key.c_str(), key.length(),
544 &value[0], value.size(), 0, 0);
545 return (rc == MEMCACHED_SUCCESS);
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.
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
558 bool addByKey(const std::string &master_key,
559 const std::string &key,
560 const std::vector<char> &value) throw(Error)
562 if (master_key.empty() ||
566 throw(Error("the master key or key supplied is empty!", false));
568 memcached_return rc= memcached_add_by_key(&memc,
576 return (rc == MEMCACHED_SUCCESS);
580 * Replaces an object on the server. This method only succeeds
581 * if the object is already present on the server.
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
587 bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
592 throw(Error("the key or value supplied is empty!", false));
594 memcached_return rc= memcached_replace(&memc, key.c_str(), key.length(),
595 &value[0], value.size(),
597 return (rc == MEMCACHED_SUCCESS);
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.
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
610 bool replaceByKey(const std::string &master_key,
611 const std::string &key,
612 const std::vector<char> &value)
614 if (master_key.empty() ||
618 throw(Error("the master key or key supplied is empty!", false));
620 memcached_return rc= memcached_replace_by_key(&memc,
628 return (rc == MEMCACHED_SUCCESS);
632 * Places a segment of data before the last piece of data stored.
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
638 bool prepend(const std::string &key, const std::vector<char> &value)
641 if (key.empty() || value.empty())
643 throw(Error("the key or value supplied is empty!", false));
645 memcached_return rc= memcached_prepend(&memc, key.c_str(), key.length(),
646 &value[0], value.size(), 0, 0);
647 return (rc == MEMCACHED_SUCCESS);
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.
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
660 bool prependByKey(const std::string &master_key,
661 const std::string &key,
662 const std::vector<char> &value)
665 if (master_key.empty() ||
669 throw(Error("the master key or key supplied is empty!", false));
671 memcached_return rc= memcached_prepend_by_key(&memc,
680 return (rc == MEMCACHED_SUCCESS);
684 * Places a segment of data at the end of the last piece of data stored.
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
690 bool append(const std::string &key, const std::vector<char> &value)
693 if (key.empty() || value.empty())
695 throw(Error("the key or value supplied is empty!", false));
697 memcached_return rc= memcached_append(&memc,
703 return (rc == MEMCACHED_SUCCESS);
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.
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
716 bool appendByKey(const std::string &master_key,
717 const std::string &key,
718 const std::vector<char> &value)
721 if (master_key.empty() ||
725 throw(Error("the master key or key supplied is empty!", false));
727 memcached_return rc= memcached_append_by_key(&memc,
735 return (rc == MEMCACHED_SUCCESS);
739 * Overwrite data in the server as long as the cas_arg value
740 * is still the same in the server.
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
746 bool cas(const std::string &key,
747 const std::vector<char> &value,
748 uint64_t cas_arg) throw(Error)
750 if (key.empty() || value.empty())
752 throw(Error("the key or value supplied is empty!", false));
754 memcached_return rc= memcached_cas(&memc, key.c_str(), key.length(),
755 &value[0], value.size(),
757 return (rc == MEMCACHED_SUCCESS);
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.
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
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)
775 if (master_key.empty() ||
779 throw(Error("the master key, key or value supplied is empty!", false));
781 memcached_return rc= memcached_cas_by_key(&memc,
789 return (rc == MEMCACHED_SUCCESS);
793 * Delete an object from the server specified by the key given.
795 * @param[in] key key of object to delete
796 * @return true on success; false otherwise
798 bool remove(const std::string &key) throw(Error)
802 throw(Error("the key supplied is empty!", false));
804 memcached_return rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
805 return (rc == MEMCACHED_SUCCESS);
809 * Delete an object from the server specified by the key given.
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
815 bool remove(const std::string &key,
816 time_t expiration) throw(Error)
820 throw(Error("the key supplied is empty!", false));
822 memcached_return rc= memcached_delete(&memc,
826 return (rc == MEMCACHED_SUCCESS);
830 * Delete an object from the server specified by the key given.
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
836 bool removeByKey(const std::string &master_key,
837 const std::string &key) throw(Error)
839 if (master_key.empty() || key.empty())
841 throw(Error("the master key or key supplied is empty!", false));
843 memcached_return rc= memcached_delete_by_key(&memc,
849 return (rc == MEMCACHED_SUCCESS);
853 * Delete an object from the server specified by the key given.
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
860 bool removeByKey(const std::string &master_key,
861 const std::string &key,
862 time_t expiration) throw(Error)
864 if (master_key.empty() || key.empty())
866 throw(Error("the master key or key supplied is empty!", false));
868 memcached_return rc= memcached_delete_by_key(&memc,
874 return (rc == MEMCACHED_SUCCESS);
878 * Wipe the contents of memcached servers.
880 * @param[in] expiration time to wait until wiping contents of
882 * @return true on success; false otherwise
884 bool flush(time_t expiration)
886 memcached_return rc= memcached_flush(&memc, expiration);
887 return (rc == MEMCACHED_SUCCESS);
891 * Callback function for result sets. It passes the result
892 * sets to the list of functions provided.
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
900 bool fetchExecute(memcached_execute_function *callback,
902 unsigned int num_of_callbacks)
904 memcached_return rc= memcached_fetch_execute(&memc,
908 return (rc == MEMCACHED_SUCCESS);
912 * Get the library version string.
913 * @return std::string containing a copy of the library version string.
915 const std::string libVersion() const
917 const char *ver= memcached_lib_version();
918 const std::string version(ver);
924 std::string servers_list;
926 memcached_server_st *servers;
927 memcached_result_st result;
932 #endif /* LIBMEMCACHEDPP_H */