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());
60 Memcache(const std::string &hostname,
68 memcached_create(&memc);
69 servers_list.append(hostname);
70 servers_list.append(":");
71 std::ostringstream strsmt;
73 servers_list.append(strsmt.str());
74 servers= memcached_servers_parse(servers_list.c_str());
77 Memcache(memcached_st *clone)
84 memcached_clone(&memc, clone);
87 Memcache(const Memcache &rhs)
89 servers_list(rhs.servers_list),
94 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
95 servers= memcached_servers_parse(servers_list.c_str());
98 Memcache &operator=(const Memcache &rhs)
102 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
103 servers= memcached_servers_parse(servers_list.c_str());
110 memcached_free(&memc);
111 memcached_server_list_free(servers);
115 * Get the internal memcached_st *
117 memcached_st &getImpl()
123 * Get the internal memcached_st *
125 const memcached_st &getImpl() const
131 * Return an error string for the given return structure.
133 * @param[in] rc a memcached_return structure
134 * @return error string corresponding to given return code in the library.
136 const std::string getError(memcached_return rc) const
138 /* first parameter to strerror is unused */
139 return memcached_strerror(NULL, rc);
143 * Return the string which contains the list of memcached servers being
146 * @return a std::string containing the list of memcached servers
148 const std::string getServersList() const
154 * Set the list of memcached servers to use.
156 * @param[in] in_servers_list list of servers
157 * @return true on success; false otherwise
159 bool setServers(const std::string &in_servers_list)
161 servers_list.assign(in_servers_list);
162 servers= memcached_servers_parse(in_servers_list.c_str());
163 return (servers == NULL);
167 * Add a server to the list of memcached servers to use.
169 * @param[in] server_name name of the server to add
170 * @param[in[ port port number of server to add
171 * @return true on success; false otherwise
173 bool addServer(const std::string &server_name, unsigned int port)
176 std::ostringstream strstm;
177 servers_list.append(",");
178 servers_list.append(server_name);
179 servers_list.append(":");
181 servers_list.append(strstm.str());
182 servers= memcached_server_list_append(servers,
186 return (rc == MEMCACHED_SUCCESS);
190 * Fetches an individual value from the server. mget() must always
191 * be called before using this method.
193 * @param[in] key key of object to fetch
194 * @param[out] ret_val store returned object in this vector
195 * @return a memcached return structure
197 memcached_return fetch(std::string &key,
198 std::vector<char> &ret_val)
200 char ret_key[MEMCACHED_MAX_KEY];
201 size_t value_length= 0;
202 size_t key_length= 0;
205 char *value= memcached_fetch(&memc, ret_key, &key_length,
206 &value_length, &flags, &rc);
207 if (value && ret_val.empty())
209 ret_val.reserve(value_length);
210 ret_val.assign(value, value + value_length);
217 * Fetches an individual value from the server.
219 * @param[in] key key of object whose value to get
220 * @param[out] ret_val object that is retrieved is stored in
222 * @return true on success; false otherwise
224 bool get(const std::string &key,
225 std::vector<char> &ret_val) throw (Error)
229 size_t value_length= 0;
233 throw(Error("the key supplied is empty!", false));
235 char *value= memcached_get(&memc, key.c_str(), key.length(),
236 &value_length, &flags, &rc);
237 if (value != NULL && ret_val.empty())
239 ret_val.reserve(value_length);
240 ret_val.assign(value, value + value_length);
247 * Fetches an individual from a server which is specified by
248 * the master_key parameter that is used for determining which
249 * server an object was stored in if key partitioning was
252 * @param[in] master_key key that specifies server object is stored on
253 * @param[in] key key of object whose value to get
254 * @param[out] ret_val object that is retrieved is stored in
256 * @return true on success; false otherwise
258 bool getByKey(const std::string &master_key,
259 const std::string &key,
260 std::vector<char> &ret_val) throw(Error)
264 size_t value_length= 0;
266 if (master_key.empty() || key.empty())
268 throw(Error("the master key or key supplied is empty!", false));
270 char *value= memcached_get_by_key(&memc,
271 master_key.c_str(), master_key.length(),
272 key.c_str(), key.length(),
273 &value_length, &flags, &rc);
276 ret_val.reserve(value_length);
277 ret_val.assign(value, value + value_length);
284 * Selects multiple keys at once. This method always
285 * works asynchronously.
287 * @param[in] keys vector of keys to select
288 * @return true if all keys are found
290 bool mget(std::vector<std::string> &keys)
292 std::vector<const char *> real_keys;
293 std::vector<size_t> key_len;
295 * Construct an array which will contain the length
296 * of each of the strings in the input vector. Also, to
297 * interface with the memcached C API, we need to convert
298 * the vector of std::string's to a vector of char *.
300 real_keys.reserve(keys.size());
301 key_len.reserve(keys.size());
303 std::vector<std::string>::iterator it= keys.begin();
305 while (it != keys.end())
307 real_keys.push_back(const_cast<char *>((*it).c_str()));
308 key_len.push_back((*it).length());
313 * If the std::vector of keys is empty then we cannot
314 * call memcached_mget as we will get undefined behavior.
316 if (! real_keys.empty())
318 memcached_return rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
320 return (rc == MEMCACHED_SUCCESS);
327 * Writes an object to the server. If the object already exists, it will
328 * overwrite the existing object. This method always returns true
329 * when using non-blocking mode unless a network error occurs.
331 * @param[in] key key of object to write to server
332 * @param[in] value value of object to write to server
333 * @param[in] expiration time to keep the object stored in the server for
334 * @param[in] flags flags to store with the object
335 * @return true on succcess; false otherwise
337 bool set(const std::string &key,
338 const std::vector<char> &value,
340 uint32_t flags) throw(Error)
342 if (key.empty() || value.empty())
344 throw(Error("the key or value supplied is empty!", false));
346 memcached_return rc= memcached_set(&memc,
347 key.c_str(), key.length(),
348 &value[0], value.size(),
350 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
354 * Writes an object to a server specified by the master_key parameter.
355 * If the object already exists, it will overwrite the existing object.
357 * @param[in] master_key key that specifies server to write to
358 * @param[in] key key of object to write to server
359 * @param[in] value value of object to write to server
360 * @param[in] expiration time to keep the object stored in the server for
361 * @param[in] flags flags to store with the object
362 * @return true on succcess; false otherwise
364 bool setByKey(const std::string &master_key,
365 const std::string &key,
366 const std::vector<char> &value,
368 uint32_t flags) throw(Error)
370 if (master_key.empty() ||
374 throw(Error("the key or value supplied is empty!", false));
376 memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(),
378 key.c_str(), key.length(),
379 &value[0], value.size(),
382 return (rc == MEMCACHED_SUCCESS);
386 * Writes a list of objects to the server. Objects are specified by
387 * 2 vectors - 1 vector of keys and 1 vector of values.
389 * @param[in] keys vector of keys of objects to write to server
390 * @param[in] values vector of values of objects to write to server
391 * @param[in] expiration time to keep the objects stored in server for
392 * @param[in] flags flags to store with the objects
393 * @return true on success; false otherwise
395 bool setAll(std::vector<std::string> &keys,
396 std::vector< std::vector<char> *> &values,
398 uint32_t flags) throw(Error)
400 if (keys.size() != values.size())
402 throw(Error("The number of keys and values do not match!", false));
405 std::vector<std::string>::iterator key_it= keys.begin();
406 std::vector< std::vector<char> *>::iterator val_it= values.begin();
407 while (key_it != keys.end())
409 retval= set((*key_it), *(*val_it), expiration, flags);
421 * Writes a list of objects to the server. Objects are specified by
422 * a map of keys to values.
424 * @param[in] key_value_map map of keys and values to store in server
425 * @param[in] expiration time to keep the objects stored in server for
426 * @param[in] flags flags to store with the objects
427 * @return true on success; false otherwise
429 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
431 uint32_t flags) throw(Error)
433 if (key_value_map.empty())
435 throw(Error("The key/values are not properly set!", false));
438 std::map<const std::string, std::vector<char> >::iterator it=
439 key_value_map.begin();
440 while (it != key_value_map.end())
442 retval= set(it->first, it->second, expiration, flags);
446 sprintf(err_buff, "There was an error setting the key %s",
448 throw(Error(err_buff, false));
456 * Increment the value of the object associated with the specified
457 * key by the offset given. The resulting value is saved in the value
460 * @param[in] key key of object in server whose value to increment
461 * @param[in] offset amount to increment object's value by
462 * @param[out] value store the result of the increment here
463 * @return true on success; false otherwise
465 bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
469 throw(Error("the key supplied is empty!", false));
471 memcached_return rc= memcached_increment(&memc, key.c_str(), key.length(),
473 return (rc == MEMCACHED_SUCCESS);
477 * Decrement the value of the object associated with the specified
478 * key by the offset given. The resulting value is saved in the value
481 * @param[in] key key of object in server whose value to decrement
482 * @param[in] offset amount to increment object's value by
483 * @param[out] value store the result of the decrement here
484 * @return true on success; false otherwise
486 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
491 throw(Error("the key supplied is empty!", false));
493 memcached_return rc= memcached_decrement(&memc, key.c_str(),
496 return (rc == MEMCACHED_SUCCESS);
501 * Add an object with the specified key and value to the server. This
502 * function returns false if the object already exists on the server.
504 * @param[in] key key of object to add
505 * @param[in] value of object to add
506 * @return true on success; false otherwise
508 bool add(const std::string &key, const std::vector<char> &value)
511 if (key.empty() || value.empty())
513 throw(Error("the key or value supplied is empty!", false));
515 memcached_return rc= memcached_add(&memc, key.c_str(), key.length(),
516 &value[0], value.size(), 0, 0);
517 return (rc == MEMCACHED_SUCCESS);
521 * Add an object with the specified key and value to the server. This
522 * function returns false if the object already exists on the server. The
523 * server to add the object to is specified by the master_key parameter.
525 * @param[in[ master_key key of server to add object to
526 * @param[in] key key of object to add
527 * @param[in] value of object to add
528 * @return true on success; false otherwise
530 bool addByKey(const std::string &master_key,
531 const std::string &key,
532 const std::vector<char> &value) throw(Error)
534 if (master_key.empty() ||
538 throw(Error("the master key or key supplied is empty!", false));
540 memcached_return rc= memcached_add_by_key(&memc,
548 return (rc == MEMCACHED_SUCCESS);
552 * Replaces an object on the server. This method only succeeds
553 * if the object is already present on the server.
555 * @param[in] key key of object to replace
556 * @param[in[ value value to replace object with
557 * @return true on success; false otherwise
559 bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
564 throw(Error("the key or value supplied is empty!", false));
566 memcached_return rc= memcached_replace(&memc, key.c_str(), key.length(),
567 &value[0], value.size(),
569 return (rc == MEMCACHED_SUCCESS);
573 * Replaces an object on the server. This method only succeeds
574 * if the object is already present on the server. The server
575 * to replace the object on is specified by the master_key param.
577 * @param[in] master_key key of server to replace object on
578 * @param[in] key key of object to replace
579 * @param[in[ value value to replace object with
580 * @return true on success; false otherwise
582 bool replaceByKey(const std::string &master_key,
583 const std::string &key,
584 const std::vector<char> &value)
586 if (master_key.empty() ||
590 throw(Error("the master key or key supplied is empty!", false));
592 memcached_return rc= memcached_replace_by_key(&memc,
600 return (rc == MEMCACHED_SUCCESS);
604 * Places a segment of data before the last piece of data stored.
606 * @param[in] key key of object whose value we will prepend data to
607 * @param[in] value data to prepend to object's value
608 * @return true on success; false otherwise
610 bool prepend(const std::string &key, const std::vector<char> &value)
613 if (key.empty() || value.empty())
615 throw(Error("the key or value supplied is empty!", false));
617 memcached_return rc= memcached_prepend(&memc, key.c_str(), key.length(),
618 &value[0], value.size(), 0, 0);
619 return (rc == MEMCACHED_SUCCESS);
623 * Places a segment of data before the last piece of data stored. The
624 * server on which the object where we will be prepending data is stored
625 * on is specified by the master_key parameter.
627 * @param[in] master_key key of server where object is stored
628 * @param[in] key key of object whose value we will prepend data to
629 * @param[in] value data to prepend to object's value
630 * @return true on success; false otherwise
632 bool prependByKey(const std::string &master_key,
633 const std::string &key,
634 const std::vector<char> &value)
637 if (master_key.empty() ||
641 throw(Error("the master key or key supplied is empty!", false));
643 memcached_return rc= memcached_prepend_by_key(&memc,
652 return (rc == MEMCACHED_SUCCESS);
656 * Places a segment of data at the end of the last piece of data stored.
658 * @param[in] key key of object whose value we will append data to
659 * @param[in] value data to append to object's value
660 * @return true on success; false otherwise
662 bool append(const std::string &key, const std::vector<char> &value)
665 if (key.empty() || value.empty())
667 throw(Error("the key or value supplied is empty!", false));
669 memcached_return rc= memcached_append(&memc,
675 return (rc == MEMCACHED_SUCCESS);
679 * Places a segment of data at the end of the last piece of data stored. The
680 * server on which the object where we will be appending data is stored
681 * on is specified by the master_key parameter.
683 * @param[in] master_key key of server where object is stored
684 * @param[in] key key of object whose value we will append data to
685 * @param[in] value data to append to object's value
686 * @return true on success; false otherwise
688 bool appendByKey(const std::string &master_key,
689 const std::string &key,
690 const std::vector<char> &value)
693 if (master_key.empty() ||
697 throw(Error("the master key or key supplied is empty!", false));
699 memcached_return rc= memcached_append_by_key(&memc,
707 return (rc == MEMCACHED_SUCCESS);
711 * Overwrite data in the server as long as the cas_arg value
712 * is still the same in the server.
714 * @param[in] key key of object in server
715 * @param[in] value value to store for object in server
716 * @param[in] cas_arg "cas" value
718 bool cas(const std::string &key,
719 const std::vector<char> &value,
720 uint64_t cas_arg) throw(Error)
722 if (key.empty() || value.empty())
724 throw(Error("the key or value supplied is empty!", false));
726 memcached_return rc= memcached_cas(&memc, key.c_str(), key.length(),
727 &value[0], value.size(),
729 return (rc == MEMCACHED_SUCCESS);
733 * Overwrite data in the server as long as the cas_arg value
734 * is still the same in the server. The server to use is
735 * specified by the master_key parameter.
737 * @param[in] master_key specifies server to operate on
738 * @param[in] key key of object in server
739 * @param[in] value value to store for object in server
740 * @param[in] cas_arg "cas" value
742 bool casByKey(const std::string &master_key,
743 const std::string &key,
744 const std::vector<char> &value,
745 uint64_t cas_arg) throw(Error)
747 if (master_key.empty() ||
751 throw(Error("the master key, key or value supplied is empty!", false));
753 memcached_return rc= memcached_cas_by_key(&memc,
761 return (rc == MEMCACHED_SUCCESS);
765 * Delete an object from the server specified by the key given.
767 * @param[in] key key of object to delete
768 * @return true on success; false otherwise
770 bool remove(const std::string &key) throw(Error)
774 throw(Error("the key supplied is empty!", false));
776 memcached_return rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
777 return (rc == MEMCACHED_SUCCESS);
781 * Delete an object from the server specified by the key given.
783 * @param[in] key key of object to delete
784 * @param[in] expiration time to delete the object after
785 * @return true on success; false otherwise
787 bool remove(const std::string &key,
788 time_t expiration) throw(Error)
792 throw(Error("the key supplied is empty!", false));
794 memcached_return rc= memcached_delete(&memc,
798 return (rc == MEMCACHED_SUCCESS);
802 * Delete an object from the server specified by the key given.
804 * @param[in] master_key specifies server to remove object from
805 * @param[in] key key of object to delete
806 * @return true on success; false otherwise
808 bool removeByKey(const std::string &master_key,
809 const std::string &key) throw(Error)
811 if (master_key.empty() || key.empty())
813 throw(Error("the master key or key supplied is empty!", false));
815 memcached_return rc= memcached_delete_by_key(&memc,
821 return (rc == MEMCACHED_SUCCESS);
825 * Delete an object from the server specified by the key given.
827 * @param[in] master_key specifies server to remove object from
828 * @param[in] key key of object to delete
829 * @param[in] expiration time to delete the object after
830 * @return true on success; false otherwise
832 bool removeByKey(const std::string &master_key,
833 const std::string &key,
834 time_t expiration) throw(Error)
836 if (master_key.empty() || key.empty())
838 throw(Error("the master key or key supplied is empty!", false));
840 memcached_return rc= memcached_delete_by_key(&memc,
846 return (rc == MEMCACHED_SUCCESS);
850 * Wipe the contents of memcached servers.
852 * @param[in] expiration time to wait until wiping contents of
854 * @return true on success; false otherwise
856 bool flush(time_t expiration)
858 memcached_return rc= memcached_flush(&memc, expiration);
859 return (rc == MEMCACHED_SUCCESS);
863 * Callback function for result sets. It passes the result
864 * sets to the list of functions provided.
866 * @param[in] callback list of callback functions
867 * @param[in] context pointer to memory reference that is
868 * supplied to the calling function
869 * @param[in] num_of_callbacks number of callback functions
870 * @return true on success; false otherwise
872 bool fetchExecute(memcached_execute_function *callback,
874 unsigned int num_of_callbacks)
876 memcached_return rc= memcached_fetch_execute(&memc,
880 return (rc == MEMCACHED_SUCCESS);
884 * Get the library version string.
885 * @return std::string containing a copy of the library version string.
887 const std::string libVersion() const
889 const char *ver= memcached_lib_version();
890 const std::string version(ver);
896 std::string servers_list;
898 memcached_server_st *servers;
899 memcached_result_st result;
904 #endif /* LIBMEMCACHEDPP_H */