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);
245 * Fetches an individual value from the server.
247 * @param[in] key key of object whose value to get
248 * @param[out] ret_val object that is retrieved is stored in
250 * @return true on success; false otherwise
252 bool get(const std::string &key,
253 std::vector<char> &ret_val) throw (Error)
257 size_t value_length= 0;
261 throw(Error("the key supplied is empty!", false));
263 char *value= memcached_get(&memc, key.c_str(), key.length(),
264 &value_length, &flags, &rc);
265 if (value != NULL && ret_val.empty())
267 ret_val.reserve(value_length);
268 ret_val.assign(value, value + value_length);
276 * Fetches an individual from a server which is specified by
277 * the master_key parameter that is used for determining which
278 * server an object was stored in if key partitioning was
281 * @param[in] master_key key that specifies server object is stored on
282 * @param[in] key key of object whose value to get
283 * @param[out] ret_val object that is retrieved is stored in
285 * @return true on success; false otherwise
287 bool getByKey(const std::string &master_key,
288 const std::string &key,
289 std::vector<char> &ret_val) throw(Error)
293 size_t value_length= 0;
295 if (master_key.empty() || key.empty())
297 throw(Error("the master key or key supplied is empty!", false));
299 char *value= memcached_get_by_key(&memc,
300 master_key.c_str(), master_key.length(),
301 key.c_str(), key.length(),
302 &value_length, &flags, &rc);
305 ret_val.reserve(value_length);
306 ret_val.assign(value, value + value_length);
314 * Selects multiple keys at once. This method always
315 * works asynchronously.
317 * @param[in] keys vector of keys to select
318 * @return true if all keys are found
320 bool mget(std::vector<std::string> &keys)
322 std::vector<const char *> real_keys;
323 std::vector<size_t> key_len;
325 * Construct an array which will contain the length
326 * of each of the strings in the input vector. Also, to
327 * interface with the memcached C API, we need to convert
328 * the vector of std::string's to a vector of char *.
330 real_keys.reserve(keys.size());
331 key_len.reserve(keys.size());
333 std::vector<std::string>::iterator it= keys.begin();
335 while (it != keys.end())
337 real_keys.push_back(const_cast<char *>((*it).c_str()));
338 key_len.push_back((*it).length());
343 * If the std::vector of keys is empty then we cannot
344 * call memcached_mget as we will get undefined behavior.
346 if (! real_keys.empty())
348 memcached_return rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
350 return (rc == MEMCACHED_SUCCESS);
357 * Writes an object to the server. If the object already exists, it will
358 * overwrite the existing object. This method always returns true
359 * when using non-blocking mode unless a network error occurs.
361 * @param[in] key key of object to write to server
362 * @param[in] value value of object to write to server
363 * @param[in] expiration time to keep the object stored in the server for
364 * @param[in] flags flags to store with the object
365 * @return true on succcess; false otherwise
367 bool set(const std::string &key,
368 const std::vector<char> &value,
370 uint32_t flags) throw(Error)
372 if (key.empty() || value.empty())
374 throw(Error("the key or value supplied is empty!", false));
376 memcached_return rc= memcached_set(&memc,
377 key.c_str(), key.length(),
378 &value[0], value.size(),
380 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
384 * Writes an object to a server specified by the master_key parameter.
385 * If the object already exists, it will overwrite the existing object.
387 * @param[in] master_key key that specifies server to write to
388 * @param[in] key key of object to write to server
389 * @param[in] value value of object to write to server
390 * @param[in] expiration time to keep the object stored in the server for
391 * @param[in] flags flags to store with the object
392 * @return true on succcess; false otherwise
394 bool setByKey(const std::string &master_key,
395 const std::string &key,
396 const std::vector<char> &value,
398 uint32_t flags) throw(Error)
400 if (master_key.empty() ||
404 throw(Error("the key or value supplied is empty!", false));
406 memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(),
408 key.c_str(), key.length(),
409 &value[0], value.size(),
412 return (rc == MEMCACHED_SUCCESS);
416 * Writes a list of objects to the server. Objects are specified by
417 * 2 vectors - 1 vector of keys and 1 vector of values.
419 * @param[in] keys vector of keys of objects to write to server
420 * @param[in] values vector of values of objects to write to server
421 * @param[in] expiration time to keep the objects stored in server for
422 * @param[in] flags flags to store with the objects
423 * @return true on success; false otherwise
425 bool setAll(std::vector<std::string> &keys,
426 std::vector< std::vector<char> *> &values,
428 uint32_t flags) throw(Error)
430 if (keys.size() != values.size())
432 throw(Error("The number of keys and values do not match!", false));
435 std::vector<std::string>::iterator key_it= keys.begin();
436 std::vector< std::vector<char> *>::iterator val_it= values.begin();
437 while (key_it != keys.end())
439 retval= set((*key_it), *(*val_it), expiration, flags);
451 * Writes a list of objects to the server. Objects are specified by
452 * a map of keys to values.
454 * @param[in] key_value_map map of keys and values to store in server
455 * @param[in] expiration time to keep the objects stored in server for
456 * @param[in] flags flags to store with the objects
457 * @return true on success; false otherwise
459 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
461 uint32_t flags) throw(Error)
463 if (key_value_map.empty())
465 throw(Error("The key/values are not properly set!", false));
468 std::map<const std::string, std::vector<char> >::iterator it=
469 key_value_map.begin();
470 while (it != key_value_map.end())
472 retval= set(it->first, it->second, expiration, flags);
475 std::string err_buff("There was an error setting the key ");
476 err_buff.append(it->first);
477 throw(Error(err_buff, false));
485 * Increment the value of the object associated with the specified
486 * key by the offset given. The resulting value is saved in the value
489 * @param[in] key key of object in server whose value to increment
490 * @param[in] offset amount to increment object's value by
491 * @param[out] value store the result of the increment here
492 * @return true on success; false otherwise
494 bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
498 throw(Error("the key supplied is empty!", false));
500 memcached_return rc= memcached_increment(&memc, key.c_str(), key.length(),
502 return (rc == MEMCACHED_SUCCESS);
506 * Decrement the value of the object associated with the specified
507 * key by the offset given. The resulting value is saved in the value
510 * @param[in] key key of object in server whose value to decrement
511 * @param[in] offset amount to increment object's value by
512 * @param[out] value store the result of the decrement here
513 * @return true on success; false otherwise
515 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
520 throw(Error("the key supplied is empty!", false));
522 memcached_return rc= memcached_decrement(&memc, key.c_str(),
525 return (rc == MEMCACHED_SUCCESS);
530 * Add an object with the specified key and value to the server. This
531 * function returns false if the object already exists on the server.
533 * @param[in] key key of object to add
534 * @param[in] value of object to add
535 * @return true on success; false otherwise
537 bool add(const std::string &key, const std::vector<char> &value)
540 if (key.empty() || value.empty())
542 throw(Error("the key or value supplied is empty!", false));
544 memcached_return rc= memcached_add(&memc, key.c_str(), key.length(),
545 &value[0], value.size(), 0, 0);
546 return (rc == MEMCACHED_SUCCESS);
550 * Add an object with the specified key and value to the server. This
551 * function returns false if the object already exists on the server. The
552 * server to add the object to is specified by the master_key parameter.
554 * @param[in[ master_key key of server to add object to
555 * @param[in] key key of object to add
556 * @param[in] value of object to add
557 * @return true on success; false otherwise
559 bool addByKey(const std::string &master_key,
560 const std::string &key,
561 const std::vector<char> &value) throw(Error)
563 if (master_key.empty() ||
567 throw(Error("the master key or key supplied is empty!", false));
569 memcached_return rc= memcached_add_by_key(&memc,
577 return (rc == MEMCACHED_SUCCESS);
581 * Replaces an object on the server. This method only succeeds
582 * if the object is already present on the server.
584 * @param[in] key key of object to replace
585 * @param[in[ value value to replace object with
586 * @return true on success; false otherwise
588 bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
593 throw(Error("the key or value supplied is empty!", false));
595 memcached_return rc= memcached_replace(&memc, key.c_str(), key.length(),
596 &value[0], value.size(),
598 return (rc == MEMCACHED_SUCCESS);
602 * Replaces an object on the server. This method only succeeds
603 * if the object is already present on the server. The server
604 * to replace the object on is specified by the master_key param.
606 * @param[in] master_key key of server to replace object on
607 * @param[in] key key of object to replace
608 * @param[in[ value value to replace object with
609 * @return true on success; false otherwise
611 bool replaceByKey(const std::string &master_key,
612 const std::string &key,
613 const std::vector<char> &value)
615 if (master_key.empty() ||
619 throw(Error("the master key or key supplied is empty!", false));
621 memcached_return rc= memcached_replace_by_key(&memc,
629 return (rc == MEMCACHED_SUCCESS);
633 * Places a segment of data before the last piece of data stored.
635 * @param[in] key key of object whose value we will prepend data to
636 * @param[in] value data to prepend to object's value
637 * @return true on success; false otherwise
639 bool prepend(const std::string &key, const std::vector<char> &value)
642 if (key.empty() || value.empty())
644 throw(Error("the key or value supplied is empty!", false));
646 memcached_return rc= memcached_prepend(&memc, key.c_str(), key.length(),
647 &value[0], value.size(), 0, 0);
648 return (rc == MEMCACHED_SUCCESS);
652 * Places a segment of data before the last piece of data stored. The
653 * server on which the object where we will be prepending data is stored
654 * on is specified by the master_key parameter.
656 * @param[in] master_key key of server where object is stored
657 * @param[in] key key of object whose value we will prepend data to
658 * @param[in] value data to prepend to object's value
659 * @return true on success; false otherwise
661 bool prependByKey(const std::string &master_key,
662 const std::string &key,
663 const std::vector<char> &value)
666 if (master_key.empty() ||
670 throw(Error("the master key or key supplied is empty!", false));
672 memcached_return rc= memcached_prepend_by_key(&memc,
681 return (rc == MEMCACHED_SUCCESS);
685 * Places a segment of data at the end of the last piece of data stored.
687 * @param[in] key key of object whose value we will append data to
688 * @param[in] value data to append to object's value
689 * @return true on success; false otherwise
691 bool append(const std::string &key, const std::vector<char> &value)
694 if (key.empty() || value.empty())
696 throw(Error("the key or value supplied is empty!", false));
698 memcached_return rc= memcached_append(&memc,
704 return (rc == MEMCACHED_SUCCESS);
708 * Places a segment of data at the end of the last piece of data stored. The
709 * server on which the object where we will be appending data is stored
710 * on is specified by the master_key parameter.
712 * @param[in] master_key key of server where object is stored
713 * @param[in] key key of object whose value we will append data to
714 * @param[in] value data to append to object's value
715 * @return true on success; false otherwise
717 bool appendByKey(const std::string &master_key,
718 const std::string &key,
719 const std::vector<char> &value)
722 if (master_key.empty() ||
726 throw(Error("the master key or key supplied is empty!", false));
728 memcached_return rc= memcached_append_by_key(&memc,
736 return (rc == MEMCACHED_SUCCESS);
740 * Overwrite data in the server as long as the cas_arg value
741 * is still the same in the server.
743 * @param[in] key key of object in server
744 * @param[in] value value to store for object in server
745 * @param[in] cas_arg "cas" value
747 bool cas(const std::string &key,
748 const std::vector<char> &value,
749 uint64_t cas_arg) throw(Error)
751 if (key.empty() || value.empty())
753 throw(Error("the key or value supplied is empty!", false));
755 memcached_return rc= memcached_cas(&memc, key.c_str(), key.length(),
756 &value[0], value.size(),
758 return (rc == MEMCACHED_SUCCESS);
762 * Overwrite data in the server as long as the cas_arg value
763 * is still the same in the server. The server to use is
764 * specified by the master_key parameter.
766 * @param[in] master_key specifies server to operate on
767 * @param[in] key key of object in server
768 * @param[in] value value to store for object in server
769 * @param[in] cas_arg "cas" value
771 bool casByKey(const std::string &master_key,
772 const std::string &key,
773 const std::vector<char> &value,
774 uint64_t cas_arg) throw(Error)
776 if (master_key.empty() ||
780 throw(Error("the master key, key or value supplied is empty!", false));
782 memcached_return rc= memcached_cas_by_key(&memc,
790 return (rc == MEMCACHED_SUCCESS);
794 * Delete an object from the server specified by the key given.
796 * @param[in] key key of object to delete
797 * @return true on success; false otherwise
799 bool remove(const std::string &key) throw(Error)
803 throw(Error("the key supplied is empty!", false));
805 memcached_return rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
806 return (rc == MEMCACHED_SUCCESS);
810 * Delete an object from the server specified by the key given.
812 * @param[in] key key of object to delete
813 * @param[in] expiration time to delete the object after
814 * @return true on success; false otherwise
816 bool remove(const std::string &key,
817 time_t expiration) throw(Error)
821 throw(Error("the key supplied is empty!", false));
823 memcached_return rc= memcached_delete(&memc,
827 return (rc == MEMCACHED_SUCCESS);
831 * Delete an object from the server specified by the key given.
833 * @param[in] master_key specifies server to remove object from
834 * @param[in] key key of object to delete
835 * @return true on success; false otherwise
837 bool removeByKey(const std::string &master_key,
838 const std::string &key) throw(Error)
840 if (master_key.empty() || key.empty())
842 throw(Error("the master key or key supplied is empty!", false));
844 memcached_return rc= memcached_delete_by_key(&memc,
850 return (rc == MEMCACHED_SUCCESS);
854 * Delete an object from the server specified by the key given.
856 * @param[in] master_key specifies server to remove object from
857 * @param[in] key key of object to delete
858 * @param[in] expiration time to delete the object after
859 * @return true on success; false otherwise
861 bool removeByKey(const std::string &master_key,
862 const std::string &key,
863 time_t expiration) throw(Error)
865 if (master_key.empty() || key.empty())
867 throw(Error("the master key or key supplied is empty!", false));
869 memcached_return rc= memcached_delete_by_key(&memc,
875 return (rc == MEMCACHED_SUCCESS);
879 * Wipe the contents of memcached servers.
881 * @param[in] expiration time to wait until wiping contents of
883 * @return true on success; false otherwise
885 bool flush(time_t expiration)
887 memcached_return rc= memcached_flush(&memc, expiration);
888 return (rc == MEMCACHED_SUCCESS);
892 * Callback function for result sets. It passes the result
893 * sets to the list of functions provided.
895 * @param[in] callback list of callback functions
896 * @param[in] context pointer to memory reference that is
897 * supplied to the calling function
898 * @param[in] num_of_callbacks number of callback functions
899 * @return true on success; false otherwise
901 bool fetchExecute(memcached_execute_function *callback,
903 unsigned int num_of_callbacks)
905 memcached_return rc= memcached_fetch_execute(&memc,
909 return (rc == MEMCACHED_SUCCESS);
913 * Get the library version string.
914 * @return std::string containing a copy of the library version string.
916 const std::string libVersion() const
918 const char *ver= memcached_lib_version();
919 const std::string version(ver);
925 std::string servers_list;
927 memcached_server_st *servers;
928 memcached_result_st result;
933 #endif /* LIBMEMCACHEDPP_H */