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
16 #ifndef LIBMEMCACHEDPP_H
17 #define LIBMEMCACHEDPP_H
19 #include <libmemcached/memcached.h>
20 #include <libmemcached/exception.hpp>
33 * This is the core memcached library (if later, other objects
34 * 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),
55 memcached_create(&memc);
59 Memcache(const std::string &hostname,
66 memcached_create(&memc);
68 servers_list.append(hostname);
69 servers_list.append(":");
70 std::ostringstream strsmt;
72 servers_list.append(strsmt.str());
77 Memcache(memcached_st *clone)
83 memcached_clone(&memc, clone);
86 Memcache(const Memcache &rhs)
88 servers_list(rhs.servers_list),
92 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
96 Memcache &operator=(const Memcache &rhs)
100 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
109 memcached_free(&memc);
114 memcached_server_st *servers;
115 servers= memcached_servers_parse(servers_list.c_str());
116 memcached_server_push(&memc, servers);
117 memcached_server_free(servers);
121 * Get the internal memcached_st *
123 memcached_st &getImpl()
129 * Get the internal memcached_st *
131 const memcached_st &getImpl() const
137 * Return an error string for the given return structure.
139 * @param[in] rc a memcached_return_t structure
140 * @return error string corresponding to given return code in the library.
142 const std::string getError(memcached_return_t rc) const
144 /* first parameter to strerror is unused */
145 return memcached_strerror(NULL, rc);
149 bool setBehavior(memcached_behavior_t flag, uint64_t data)
151 memcached_return_t rc;
152 rc= memcached_behavior_set(&memc, flag, data);
153 return (rc == MEMCACHED_SUCCESS);
156 uint64_t getBehavior(memcached_behavior_t flag) {
157 return memcached_behavior_get(&memc, flag);
161 * Return the string which contains the list of memcached servers being
164 * @return a std::string containing the list of memcached servers
166 const std::string getServersList() const
172 * Set the list of memcached servers to use.
174 * @param[in] in_servers_list list of servers
175 * @return true on success; false otherwise
177 bool setServers(const std::string &in_servers_list)
179 servers_list.assign(in_servers_list);
182 return (memcached_server_count(&memc));
186 * Add a server to the list of memcached servers to use.
188 * @param[in] server_name name of the server to add
189 * @param[in] port port number of server to add
190 * @return true on success; false otherwise
192 bool addServer(const std::string &server_name, in_port_t port)
194 memcached_return_t rc;
196 rc= memcached_server_add(&memc, server_name.c_str(), port);
198 return (rc == MEMCACHED_SUCCESS);
202 * Remove a server from the list of memcached servers to use.
204 * @param[in] server_name name of the server to remove
205 * @param[in] port port number of server to remove
206 * @return true on success; false otherwise
208 bool removeServer(const std::string &server_name, in_port_t port)
211 std::ostringstream strstm;
213 tmp_str.append(server_name);
216 tmp_str.append(strstm.str());
218 //memcached_return_t rc= memcached_server_remove(server);
224 * Fetches an individual value from the server. mget() must always
225 * be called before using this method.
227 * @param[in] key key of object to fetch
228 * @param[out] ret_val store returned object in this vector
229 * @return a memcached return structure
231 memcached_return_t fetch(std::string &key,
232 std::vector<char> &ret_val)
234 char ret_key[MEMCACHED_MAX_KEY];
235 size_t value_length= 0;
236 size_t key_length= 0;
237 memcached_return_t rc;
239 char *value= memcached_fetch(&memc, ret_key, &key_length,
240 &value_length, &flags, &rc);
241 if (value && ret_val.empty())
243 ret_val.reserve(value_length);
244 ret_val.assign(value, value + value_length);
245 key.assign(ret_key, key_length);
257 * Fetches an individual value from the server.
259 * @param[in] key key of object whose value to get
260 * @param[out] ret_val object that is retrieved is stored in
262 * @return true on success; false otherwise
264 bool get(const std::string &key,
265 std::vector<char> &ret_val) throw (Error)
268 memcached_return_t rc;
269 size_t value_length= 0;
273 throw(Error("the key supplied is empty!", false));
275 char *value= memcached_get(&memc, key.c_str(), key.length(),
276 &value_length, &flags, &rc);
277 if (value != NULL && ret_val.empty())
279 ret_val.reserve(value_length);
280 ret_val.assign(value, value + value_length);
288 * Fetches an individual from a server which is specified by
289 * the master_key parameter that is used for determining which
290 * server an object was stored in if key partitioning was
293 * @param[in] master_key key that specifies server object is stored on
294 * @param[in] key key of object whose value to get
295 * @param[out] ret_val object that is retrieved is stored in
297 * @return true on success; false otherwise
299 bool getByKey(const std::string &master_key,
300 const std::string &key,
301 std::vector<char> &ret_val) throw(Error)
304 memcached_return_t rc;
305 size_t value_length= 0;
307 if (master_key.empty() || key.empty())
309 throw(Error("the master key or key supplied is empty!", false));
311 char *value= memcached_get_by_key(&memc,
312 master_key.c_str(), master_key.length(),
313 key.c_str(), key.length(),
314 &value_length, &flags, &rc);
317 ret_val.reserve(value_length);
318 ret_val.assign(value, value + value_length);
326 * Selects multiple keys at once. This method always
327 * works asynchronously.
329 * @param[in] keys vector of keys to select
330 * @return true if all keys are found
332 bool mget(std::vector<std::string> &keys)
334 std::vector<const char *> real_keys;
335 std::vector<size_t> key_len;
337 * Construct an array which will contain the length
338 * of each of the strings in the input vector. Also, to
339 * interface with the memcached C API, we need to convert
340 * the vector of std::string's to a vector of char *.
342 real_keys.reserve(keys.size());
343 key_len.reserve(keys.size());
345 std::vector<std::string>::iterator it= keys.begin();
347 while (it != keys.end())
349 real_keys.push_back(const_cast<char *>((*it).c_str()));
350 key_len.push_back((*it).length());
355 * If the std::vector of keys is empty then we cannot
356 * call memcached_mget as we will get undefined behavior.
358 if (! real_keys.empty())
360 memcached_return_t rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
362 return (rc == MEMCACHED_SUCCESS);
369 * Writes an object to the server. If the object already exists, it will
370 * overwrite the existing object. This method always returns true
371 * when using non-blocking mode unless a network error occurs.
373 * @param[in] key key of object to write to server
374 * @param[in] value value of object to write to server
375 * @param[in] expiration time to keep the object stored in the server for
376 * @param[in] flags flags to store with the object
377 * @return true on succcess; false otherwise
379 bool set(const std::string &key,
380 const std::vector<char> &value,
382 uint32_t flags) throw(Error)
384 if (key.empty() || value.empty())
386 throw(Error("the key or value supplied is empty!", false));
388 memcached_return_t rc= memcached_set(&memc,
389 key.c_str(), key.length(),
390 &value[0], value.size(),
392 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
396 * Writes an object to a server specified by the master_key parameter.
397 * If the object already exists, it will overwrite the existing object.
399 * @param[in] master_key key that specifies server to write to
400 * @param[in] key key of object to write to server
401 * @param[in] value value of object to write to server
402 * @param[in] expiration time to keep the object stored in the server for
403 * @param[in] flags flags to store with the object
404 * @return true on succcess; false otherwise
406 bool setByKey(const std::string &master_key,
407 const std::string &key,
408 const std::vector<char> &value,
410 uint32_t flags) throw(Error)
412 if (master_key.empty() ||
416 throw(Error("the key or value supplied is empty!", false));
418 memcached_return_t rc= memcached_set_by_key(&memc, master_key.c_str(),
420 key.c_str(), key.length(),
421 &value[0], value.size(),
424 return (rc == MEMCACHED_SUCCESS);
428 * Writes a list of objects to the server. Objects are specified by
429 * 2 vectors - 1 vector of keys and 1 vector of values.
431 * @param[in] keys vector of keys of objects to write to server
432 * @param[in] values vector of values of objects to write to server
433 * @param[in] expiration time to keep the objects stored in server for
434 * @param[in] flags flags to store with the objects
435 * @return true on success; false otherwise
437 bool setAll(std::vector<std::string> &keys,
438 std::vector< std::vector<char> *> &values,
440 uint32_t flags) throw(Error)
442 if (keys.size() != values.size())
444 throw(Error("The number of keys and values do not match!", false));
447 std::vector<std::string>::iterator key_it= keys.begin();
448 std::vector< std::vector<char> *>::iterator val_it= values.begin();
449 while (key_it != keys.end())
451 retval= set((*key_it), *(*val_it), expiration, flags);
463 * Writes a list of objects to the server. Objects are specified by
464 * a map of keys to values.
466 * @param[in] key_value_map map of keys and values to store in server
467 * @param[in] expiration time to keep the objects stored in server for
468 * @param[in] flags flags to store with the objects
469 * @return true on success; false otherwise
471 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
473 uint32_t flags) throw(Error)
475 if (key_value_map.empty())
477 throw(Error("The key/values are not properly set!", false));
480 std::map<const std::string, std::vector<char> >::iterator it=
481 key_value_map.begin();
482 while (it != key_value_map.end())
484 retval= set(it->first, it->second, expiration, flags);
487 std::string err_buff("There was an error setting the key ");
488 err_buff.append(it->first);
489 throw(Error(err_buff, false));
497 * Increment the value of the object associated with the specified
498 * key by the offset given. The resulting value is saved in the value
501 * @param[in] key key of object in server whose value to increment
502 * @param[in] offset amount to increment object's value by
503 * @param[out] value store the result of the increment here
504 * @return true on success; false otherwise
506 bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
510 throw(Error("the key supplied is empty!", false));
512 memcached_return_t rc= memcached_increment(&memc, key.c_str(), key.length(),
514 return (rc == MEMCACHED_SUCCESS);
518 * Decrement the value of the object associated with the specified
519 * key by the offset given. The resulting value is saved in the value
522 * @param[in] key key of object in server whose value to decrement
523 * @param[in] offset amount to increment object's value by
524 * @param[out] value store the result of the decrement here
525 * @return true on success; false otherwise
527 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
532 throw(Error("the key supplied is empty!", false));
534 memcached_return_t rc= memcached_decrement(&memc, key.c_str(),
537 return (rc == MEMCACHED_SUCCESS);
542 * Add an object with the specified key and value to the server. This
543 * function returns false if the object already exists on the server.
545 * @param[in] key key of object to add
546 * @param[in] value of object to add
547 * @return true on success; false otherwise
549 bool add(const std::string &key, const std::vector<char> &value)
552 if (key.empty() || value.empty())
554 throw(Error("the key or value supplied is empty!", false));
556 memcached_return_t rc= memcached_add(&memc, key.c_str(), key.length(),
557 &value[0], value.size(), 0, 0);
558 return (rc == MEMCACHED_SUCCESS);
562 * Add an object with the specified key and value to the server. This
563 * function returns false if the object already exists on the server. The
564 * server to add the object to is specified by the master_key parameter.
566 * @param[in[ master_key key of server to add object to
567 * @param[in] key key of object to add
568 * @param[in] value of object to add
569 * @return true on success; false otherwise
571 bool addByKey(const std::string &master_key,
572 const std::string &key,
573 const std::vector<char> &value) throw(Error)
575 if (master_key.empty() ||
579 throw(Error("the master key or key supplied is empty!", false));
581 memcached_return_t rc= memcached_add_by_key(&memc,
589 return (rc == MEMCACHED_SUCCESS);
593 * Replaces an object on the server. This method only succeeds
594 * if the object is already present on the server.
596 * @param[in] key key of object to replace
597 * @param[in[ value value to replace object with
598 * @return true on success; false otherwise
600 bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
605 throw(Error("the key or value supplied is empty!", false));
607 memcached_return_t rc= memcached_replace(&memc, key.c_str(), key.length(),
608 &value[0], value.size(),
610 return (rc == MEMCACHED_SUCCESS);
614 * Replaces an object on the server. This method only succeeds
615 * if the object is already present on the server. The server
616 * to replace the object on is specified by the master_key param.
618 * @param[in] master_key key of server to replace object on
619 * @param[in] key key of object to replace
620 * @param[in[ value value to replace object with
621 * @return true on success; false otherwise
623 bool replaceByKey(const std::string &master_key,
624 const std::string &key,
625 const std::vector<char> &value)
627 if (master_key.empty() ||
631 throw(Error("the master key or key supplied is empty!", false));
633 memcached_return_t rc= memcached_replace_by_key(&memc,
641 return (rc == MEMCACHED_SUCCESS);
645 * Places a segment of data before the last piece of data stored.
647 * @param[in] key key of object whose value we will prepend data to
648 * @param[in] value data to prepend to object's value
649 * @return true on success; false otherwise
651 bool prepend(const std::string &key, const std::vector<char> &value)
654 if (key.empty() || value.empty())
656 throw(Error("the key or value supplied is empty!", false));
658 memcached_return_t rc= memcached_prepend(&memc, key.c_str(), key.length(),
659 &value[0], value.size(), 0, 0);
660 return (rc == MEMCACHED_SUCCESS);
664 * Places a segment of data before the last piece of data stored. The
665 * server on which the object where we will be prepending data is stored
666 * on is specified by the master_key parameter.
668 * @param[in] master_key key of server where object is stored
669 * @param[in] key key of object whose value we will prepend data to
670 * @param[in] value data to prepend to object's value
671 * @return true on success; false otherwise
673 bool prependByKey(const std::string &master_key,
674 const std::string &key,
675 const std::vector<char> &value)
678 if (master_key.empty() ||
682 throw(Error("the master key or key supplied is empty!", false));
684 memcached_return_t rc= memcached_prepend_by_key(&memc,
693 return (rc == MEMCACHED_SUCCESS);
697 * Places a segment of data at the end of the last piece of data stored.
699 * @param[in] key key of object whose value we will append data to
700 * @param[in] value data to append to object's value
701 * @return true on success; false otherwise
703 bool append(const std::string &key, const std::vector<char> &value)
706 if (key.empty() || value.empty())
708 throw(Error("the key or value supplied is empty!", false));
710 memcached_return_t rc= memcached_append(&memc,
716 return (rc == MEMCACHED_SUCCESS);
720 * Places a segment of data at the end of the last piece of data stored. The
721 * server on which the object where we will be appending data is stored
722 * on is specified by the master_key parameter.
724 * @param[in] master_key key of server where object is stored
725 * @param[in] key key of object whose value we will append data to
726 * @param[in] value data to append to object's value
727 * @return true on success; false otherwise
729 bool appendByKey(const std::string &master_key,
730 const std::string &key,
731 const std::vector<char> &value)
734 if (master_key.empty() ||
738 throw(Error("the master key or key supplied is empty!", false));
740 memcached_return_t rc= memcached_append_by_key(&memc,
748 return (rc == MEMCACHED_SUCCESS);
752 * Overwrite data in the server as long as the cas_arg value
753 * is still the same in the server.
755 * @param[in] key key of object in server
756 * @param[in] value value to store for object in server
757 * @param[in] cas_arg "cas" value
759 bool cas(const std::string &key,
760 const std::vector<char> &value,
761 uint64_t cas_arg) throw(Error)
763 if (key.empty() || value.empty())
765 throw(Error("the key or value supplied is empty!", false));
767 memcached_return_t rc= memcached_cas(&memc, key.c_str(), key.length(),
768 &value[0], value.size(),
770 return (rc == MEMCACHED_SUCCESS);
774 * Overwrite data in the server as long as the cas_arg value
775 * is still the same in the server. The server to use is
776 * specified by the master_key parameter.
778 * @param[in] master_key specifies server to operate on
779 * @param[in] key key of object in server
780 * @param[in] value value to store for object in server
781 * @param[in] cas_arg "cas" value
783 bool casByKey(const std::string &master_key,
784 const std::string &key,
785 const std::vector<char> &value,
786 uint64_t cas_arg) throw(Error)
788 if (master_key.empty() ||
792 throw(Error("the master key, key or value supplied is empty!", false));
794 memcached_return_t rc= memcached_cas_by_key(&memc,
802 return (rc == MEMCACHED_SUCCESS);
806 * Delete an object from the server specified by the key given.
808 * @param[in] key key of object to delete
809 * @return true on success; false otherwise
811 bool remove(const std::string &key) throw(Error)
815 throw(Error("the key supplied is empty!", false));
817 memcached_return_t rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
818 return (rc == MEMCACHED_SUCCESS);
822 * Delete an object from the server specified by the key given.
824 * @param[in] key key of object to delete
825 * @param[in] expiration time to delete the object after
826 * @return true on success; false otherwise
828 bool remove(const std::string &key,
829 time_t expiration) throw(Error)
833 throw(Error("the key supplied is empty!", false));
835 memcached_return_t rc= memcached_delete(&memc,
839 return (rc == MEMCACHED_SUCCESS);
843 * Delete an object from the server specified by the key given.
845 * @param[in] master_key specifies server to remove object from
846 * @param[in] key key of object to delete
847 * @return true on success; false otherwise
849 bool removeByKey(const std::string &master_key,
850 const std::string &key) throw(Error)
852 if (master_key.empty() || key.empty())
854 throw(Error("the master key or key supplied is empty!", false));
856 memcached_return_t rc= memcached_delete_by_key(&memc,
862 return (rc == MEMCACHED_SUCCESS);
866 * Delete an object from the server specified by the key given.
868 * @param[in] master_key specifies server to remove object from
869 * @param[in] key key of object to delete
870 * @param[in] expiration time to delete the object after
871 * @return true on success; false otherwise
873 bool removeByKey(const std::string &master_key,
874 const std::string &key,
875 time_t expiration) throw(Error)
877 if (master_key.empty() || key.empty())
879 throw(Error("the master key or key supplied is empty!", false));
881 memcached_return_t rc= memcached_delete_by_key(&memc,
887 return (rc == MEMCACHED_SUCCESS);
891 * Wipe the contents of memcached servers.
893 * @param[in] expiration time to wait until wiping contents of
895 * @return true on success; false otherwise
897 bool flush(time_t expiration)
899 memcached_return_t rc= memcached_flush(&memc, expiration);
900 return (rc == MEMCACHED_SUCCESS);
904 * Callback function for result sets. It passes the result
905 * sets to the list of functions provided.
907 * @param[in] callback list of callback functions
908 * @param[in] context pointer to memory reference that is
909 * supplied to the calling function
910 * @param[in] num_of_callbacks number of callback functions
911 * @return true on success; false otherwise
913 bool fetchExecute(memcached_execute_fn *callback,
915 uint32_t num_of_callbacks)
917 memcached_return_t rc= memcached_fetch_execute(&memc,
921 return (rc == MEMCACHED_SUCCESS);
925 * Get the library version string.
926 * @return std::string containing a copy of the library version string.
928 const std::string libVersion() const
930 const char *ver= memcached_lib_version();
931 const std::string version(ver);
936 * Retrieve memcached statistics. Populate a std::map with the retrieved
937 * stats. Each server will map to another std::map of the key:value stats.
939 * @param[out] stats_map a std::map to be populated with the memcached
941 * @return true on success; false otherwise
943 bool getStats(std::map< std::string, std::map<std::string, std::string> >
946 memcached_return_t rc;
947 memcached_stat_st *stats= memcached_stat(&memc, NULL, &rc);
949 if (rc != MEMCACHED_SUCCESS &&
950 rc != MEMCACHED_SOME_ERRORS)
955 uint32_t server_count= memcached_server_count(&memc);
958 * For each memcached server, construct a std::map for its stats and add
959 * it to the std::map of overall stats.
961 for (uint32_t x= 0; x < server_count; x++)
963 memcached_server_instance_st instance=
964 memcached_server_instance_by_position(&memc, x);
965 std::ostringstream strstm;
966 std::string server_name(memcached_server_name(instance));
967 server_name.append(":");
968 strstm << memcached_server_port(instance);
969 server_name.append(strstm.str());
971 std::map<std::string, std::string> server_stats;
975 list= memcached_stat_get_keys(&memc, &stats[x], &rc);
976 for (ptr= list; *ptr; ptr++)
978 char *value= memcached_stat_get_value(&memc, &stats[x], *ptr, &rc);
979 server_stats[*ptr]= value;
983 stats_map[server_name]= server_stats;
987 memcached_stat_free(&memc, stats);
993 std::string servers_list;
995 memcached_result_st result;
1000 #endif /* LIBMEMCACHEDPP_H */