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);
312 * Selects multiple keys at once. This method always
313 * works asynchronously.
315 * @param[in] keys vector of keys to select
316 * @return true if all keys are found
318 bool mget(std::vector<std::string> &keys)
320 std::vector<const char *> real_keys;
321 std::vector<size_t> key_len;
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 *.
328 real_keys.reserve(keys.size());
329 key_len.reserve(keys.size());
331 std::vector<std::string>::iterator it= keys.begin();
333 while (it != keys.end())
335 real_keys.push_back(const_cast<char *>((*it).c_str()));
336 key_len.push_back((*it).length());
341 * If the std::vector of keys is empty then we cannot
342 * call memcached_mget as we will get undefined behavior.
344 if (! real_keys.empty())
346 memcached_return rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
348 return (rc == MEMCACHED_SUCCESS);
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.
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
365 bool set(const std::string &key,
366 const std::vector<char> &value,
368 uint32_t flags) throw(Error)
370 if (key.empty() || value.empty())
372 throw(Error("the key or value supplied is empty!", false));
374 memcached_return rc= memcached_set(&memc,
375 key.c_str(), key.length(),
376 &value[0], value.size(),
378 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
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.
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
392 bool setByKey(const std::string &master_key,
393 const std::string &key,
394 const std::vector<char> &value,
396 uint32_t flags) throw(Error)
398 if (master_key.empty() ||
402 throw(Error("the key or value supplied is empty!", false));
404 memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(),
406 key.c_str(), key.length(),
407 &value[0], value.size(),
410 return (rc == MEMCACHED_SUCCESS);
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.
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
423 bool setAll(std::vector<std::string> &keys,
424 std::vector< std::vector<char> *> &values,
426 uint32_t flags) throw(Error)
428 if (keys.size() != values.size())
430 throw(Error("The number of keys and values do not match!", false));
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())
437 retval= set((*key_it), *(*val_it), expiration, flags);
449 * Writes a list of objects to the server. Objects are specified by
450 * a map of keys to values.
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
457 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
459 uint32_t flags) throw(Error)
461 if (key_value_map.empty())
463 throw(Error("The key/values are not properly set!", false));
466 std::map<const std::string, std::vector<char> >::iterator it=
467 key_value_map.begin();
468 while (it != key_value_map.end())
470 retval= set(it->first, it->second, expiration, flags);
473 std::string err_buff("There was an error setting the key ");
474 err_buff.append(it->first);
475 throw(Error(err_buff, false));
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
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
492 bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
496 throw(Error("the key supplied is empty!", false));
498 memcached_return rc= memcached_increment(&memc, key.c_str(), key.length(),
500 return (rc == MEMCACHED_SUCCESS);
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
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
513 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
518 throw(Error("the key supplied is empty!", false));
520 memcached_return rc= memcached_decrement(&memc, key.c_str(),
523 return (rc == MEMCACHED_SUCCESS);
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.
531 * @param[in] key key of object to add
532 * @param[in] value of object to add
533 * @return true on success; false otherwise
535 bool add(const std::string &key, const std::vector<char> &value)
538 if (key.empty() || value.empty())
540 throw(Error("the key or value supplied is empty!", false));
542 memcached_return rc= memcached_add(&memc, key.c_str(), key.length(),
543 &value[0], value.size(), 0, 0);
544 return (rc == MEMCACHED_SUCCESS);
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.
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
557 bool addByKey(const std::string &master_key,
558 const std::string &key,
559 const std::vector<char> &value) throw(Error)
561 if (master_key.empty() ||
565 throw(Error("the master key or key supplied is empty!", false));
567 memcached_return rc= memcached_add_by_key(&memc,
575 return (rc == MEMCACHED_SUCCESS);
579 * Replaces an object on the server. This method only succeeds
580 * if the object is already present on the server.
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
586 bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
591 throw(Error("the key or value supplied is empty!", false));
593 memcached_return rc= memcached_replace(&memc, key.c_str(), key.length(),
594 &value[0], value.size(),
596 return (rc == MEMCACHED_SUCCESS);
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.
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
609 bool replaceByKey(const std::string &master_key,
610 const std::string &key,
611 const std::vector<char> &value)
613 if (master_key.empty() ||
617 throw(Error("the master key or key supplied is empty!", false));
619 memcached_return rc= memcached_replace_by_key(&memc,
627 return (rc == MEMCACHED_SUCCESS);
631 * Places a segment of data before the last piece of data stored.
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
637 bool prepend(const std::string &key, const std::vector<char> &value)
640 if (key.empty() || value.empty())
642 throw(Error("the key or value supplied is empty!", false));
644 memcached_return rc= memcached_prepend(&memc, key.c_str(), key.length(),
645 &value[0], value.size(), 0, 0);
646 return (rc == MEMCACHED_SUCCESS);
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.
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
659 bool prependByKey(const std::string &master_key,
660 const std::string &key,
661 const std::vector<char> &value)
664 if (master_key.empty() ||
668 throw(Error("the master key or key supplied is empty!", false));
670 memcached_return rc= memcached_prepend_by_key(&memc,
679 return (rc == MEMCACHED_SUCCESS);
683 * Places a segment of data at the end of the last piece of data stored.
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
689 bool append(const std::string &key, const std::vector<char> &value)
692 if (key.empty() || value.empty())
694 throw(Error("the key or value supplied is empty!", false));
696 memcached_return rc= memcached_append(&memc,
702 return (rc == MEMCACHED_SUCCESS);
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.
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
715 bool appendByKey(const std::string &master_key,
716 const std::string &key,
717 const std::vector<char> &value)
720 if (master_key.empty() ||
724 throw(Error("the master key or key supplied is empty!", false));
726 memcached_return rc= memcached_append_by_key(&memc,
734 return (rc == MEMCACHED_SUCCESS);
738 * Overwrite data in the server as long as the cas_arg value
739 * is still the same in the server.
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
745 bool cas(const std::string &key,
746 const std::vector<char> &value,
747 uint64_t cas_arg) throw(Error)
749 if (key.empty() || value.empty())
751 throw(Error("the key or value supplied is empty!", false));
753 memcached_return rc= memcached_cas(&memc, key.c_str(), key.length(),
754 &value[0], value.size(),
756 return (rc == MEMCACHED_SUCCESS);
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.
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
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)
774 if (master_key.empty() ||
778 throw(Error("the master key, key or value supplied is empty!", false));
780 memcached_return rc= memcached_cas_by_key(&memc,
788 return (rc == MEMCACHED_SUCCESS);
792 * Delete an object from the server specified by the key given.
794 * @param[in] key key of object to delete
795 * @return true on success; false otherwise
797 bool remove(const std::string &key) throw(Error)
801 throw(Error("the key supplied is empty!", false));
803 memcached_return rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
804 return (rc == MEMCACHED_SUCCESS);
808 * Delete an object from the server specified by the key given.
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
814 bool remove(const std::string &key,
815 time_t expiration) throw(Error)
819 throw(Error("the key supplied is empty!", false));
821 memcached_return rc= memcached_delete(&memc,
825 return (rc == MEMCACHED_SUCCESS);
829 * Delete an object from the server specified by the key given.
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
835 bool removeByKey(const std::string &master_key,
836 const std::string &key) throw(Error)
838 if (master_key.empty() || key.empty())
840 throw(Error("the master key or key supplied is empty!", false));
842 memcached_return rc= memcached_delete_by_key(&memc,
848 return (rc == MEMCACHED_SUCCESS);
852 * Delete an object from the server specified by the key given.
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
859 bool removeByKey(const std::string &master_key,
860 const std::string &key,
861 time_t expiration) throw(Error)
863 if (master_key.empty() || key.empty())
865 throw(Error("the master key or key supplied is empty!", false));
867 memcached_return rc= memcached_delete_by_key(&memc,
873 return (rc == MEMCACHED_SUCCESS);
877 * Wipe the contents of memcached servers.
879 * @param[in] expiration time to wait until wiping contents of
881 * @return true on success; false otherwise
883 bool flush(time_t expiration)
885 memcached_return rc= memcached_flush(&memc, expiration);
886 return (rc == MEMCACHED_SUCCESS);
890 * Callback function for result sets. It passes the result
891 * sets to the list of functions provided.
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
899 bool fetchExecute(memcached_execute_function *callback,
901 unsigned int num_of_callbacks)
903 memcached_return rc= memcached_fetch_execute(&memc,
907 return (rc == MEMCACHED_SUCCESS);
911 * Get the library version string.
912 * @return std::string containing a copy of the library version string.
914 const std::string libVersion() const
916 const char *ver= memcached_lib_version();
917 const std::string version(ver);
923 std::string servers_list;
925 memcached_server_st *servers;
926 memcached_result_st result;
931 #endif /* LIBMEMCACHEDPP_H */