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
17 #include <libmemcached/memcached.h>
18 #include <libmemcached/exception.hpp>
31 * This is the core memcached library (if later, other objects
32 * are needed, they will be created from this class).
43 memcached_create(&memc);
46 Memcache(const std::string &in_servers_list)
48 servers_list(in_servers_list),
52 memcached_create(&memc);
56 Memcache(const std::string &hostname,
63 memcached_create(&memc);
65 servers_list.append(hostname);
66 servers_list.append(":");
67 std::ostringstream strsmt;
69 servers_list.append(strsmt.str());
74 Memcache(memcached_st *clone)
80 memcached_clone(&memc, clone);
83 Memcache(const Memcache &rhs)
85 servers_list(rhs.servers_list),
89 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
93 Memcache &operator=(const Memcache &rhs)
97 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
106 memcached_free(&memc);
111 memcached_server_st *servers;
112 servers= memcached_servers_parse(servers_list.c_str());
113 memcached_server_push(&memc, servers);
114 memcached_server_free(servers);
118 * Get the internal memcached_st *
120 memcached_st &getImpl()
126 * Get the internal memcached_st *
128 const memcached_st &getImpl() const
134 * Return an error string for the given return structure.
136 * @param[in] rc a memcached_return_t structure
137 * @return error string corresponding to given return code in the library.
139 const std::string getError(memcached_return_t rc) const
141 /* first parameter to strerror is unused */
142 return memcached_strerror(NULL, rc);
146 bool setBehavior(memcached_behavior_t flag, uint64_t data)
148 memcached_return_t rc;
149 rc= memcached_behavior_set(&memc, flag, data);
150 return (rc == MEMCACHED_SUCCESS);
153 uint64_t getBehavior(memcached_behavior_t flag) {
154 return memcached_behavior_get(&memc, flag);
158 * Return the string which contains the list of memcached servers being
161 * @return a std::string containing the list of memcached servers
163 const std::string getServersList() const
169 * Set the list of memcached servers to use.
171 * @param[in] in_servers_list list of servers
172 * @return true on success; false otherwise
174 bool setServers(const std::string &in_servers_list)
176 servers_list.assign(in_servers_list);
179 return (memcached_server_count(&memc));
183 * Add a server to the list of memcached servers to use.
185 * @param[in] server_name name of the server to add
186 * @param[in] port port number of server to add
187 * @return true on success; false otherwise
189 bool addServer(const std::string &server_name, in_port_t port)
191 memcached_return_t rc;
193 rc= memcached_server_add(&memc, server_name.c_str(), port);
195 return (rc == MEMCACHED_SUCCESS);
199 * Remove a server from the list of memcached servers to use.
201 * @param[in] server_name name of the server to remove
202 * @param[in] port port number of server to remove
203 * @return true on success; false otherwise
205 bool removeServer(const std::string &server_name, in_port_t port)
208 std::ostringstream strstm;
210 tmp_str.append(server_name);
213 tmp_str.append(strstm.str());
215 //memcached_return_t rc= memcached_server_remove(server);
221 * Fetches an individual value from the server. mget() must always
222 * be called before using this method.
224 * @param[in] key key of object to fetch
225 * @param[out] ret_val store returned object in this vector
226 * @return a memcached return structure
228 memcached_return_t fetch(std::string &key,
229 std::vector<char> &ret_val)
231 char ret_key[MEMCACHED_MAX_KEY];
232 size_t value_length= 0;
233 size_t key_length= 0;
234 memcached_return_t rc;
236 char *value= memcached_fetch(&memc, ret_key, &key_length,
237 &value_length, &flags, &rc);
238 if (value && ret_val.empty())
240 ret_val.reserve(value_length);
241 ret_val.assign(value, value + value_length);
242 key.assign(ret_key, key_length);
254 * Fetches an individual value from the server.
256 * @param[in] key key of object whose value to get
257 * @param[out] ret_val object that is retrieved is stored in
259 * @return true on success; false otherwise
261 bool get(const std::string &key, std::vector<char> &ret_val)
264 memcached_return_t rc;
265 size_t value_length= 0;
267 char *value= memcached_get(&memc, key.c_str(), key.length(),
268 &value_length, &flags, &rc);
269 if (value != NULL && ret_val.empty())
271 ret_val.reserve(value_length);
272 ret_val.assign(value, value + value_length);
280 * Fetches an individual from a server which is specified by
281 * the master_key parameter that is used for determining which
282 * server an object was stored in if key partitioning was
285 * @param[in] master_key key that specifies server object is stored on
286 * @param[in] key key of object whose value to get
287 * @param[out] ret_val object that is retrieved is stored in
289 * @return true on success; false otherwise
291 bool getByKey(const std::string &master_key,
292 const std::string &key,
293 std::vector<char> &ret_val)
296 memcached_return_t rc;
297 size_t value_length= 0;
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_t 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,
372 memcached_return_t rc= memcached_set(&memc,
373 key.c_str(), key.length(),
374 &value[0], value.size(),
376 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
380 * Writes an object to a server specified by the master_key parameter.
381 * If the object already exists, it will overwrite the existing object.
383 * @param[in] master_key key that specifies server to write to
384 * @param[in] key key of object to write to server
385 * @param[in] value value of object to write to server
386 * @param[in] expiration time to keep the object stored in the server for
387 * @param[in] flags flags to store with the object
388 * @return true on succcess; false otherwise
390 bool setByKey(const std::string &master_key,
391 const std::string &key,
392 const std::vector<char> &value,
396 memcached_return_t rc= memcached_set_by_key(&memc, master_key.c_str(),
398 key.c_str(), key.length(),
399 &value[0], value.size(),
402 return (rc == MEMCACHED_SUCCESS);
406 * Writes a list of objects to the server. Objects are specified by
407 * 2 vectors - 1 vector of keys and 1 vector of values.
409 * @param[in] keys vector of keys of objects to write to server
410 * @param[in] values vector of values of objects to write to server
411 * @param[in] expiration time to keep the objects stored in server for
412 * @param[in] flags flags to store with the objects
413 * @return true on success; false otherwise
415 bool setAll(std::vector<std::string> &keys,
416 std::vector< std::vector<char> *> &values,
421 std::vector<std::string>::iterator key_it= keys.begin();
422 std::vector< std::vector<char> *>::iterator val_it= values.begin();
423 while (key_it != keys.end())
425 retval= set((*key_it), *(*val_it), expiration, flags);
437 * Writes a list of objects to the server. Objects are specified by
438 * a map of keys to values.
440 * @param[in] key_value_map map of keys and values to store in server
441 * @param[in] expiration time to keep the objects stored in server for
442 * @param[in] flags flags to store with the objects
443 * @return true on success; false otherwise
445 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
450 std::map<const std::string, std::vector<char> >::iterator it= key_value_map.begin();
452 while (it != key_value_map.end())
454 retval= set(it->first, it->second, expiration, flags);
457 // We should tell the user what the key that failed was
466 * Increment the value of the object associated with the specified
467 * key by the offset given. The resulting value is saved in the value
470 * @param[in] key key of object in server whose value to increment
471 * @param[in] offset amount to increment object's value by
472 * @param[out] value store the result of the increment here
473 * @return true on success; false otherwise
475 bool increment(const std::string &key, uint32_t offset, uint64_t *value)
477 memcached_return_t rc= memcached_increment(&memc, key.c_str(), key.length(),
479 return (rc == MEMCACHED_SUCCESS);
483 * Decrement 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 decrement
488 * @param[in] offset amount to increment object's value by
489 * @param[out] value store the result of the decrement here
490 * @return true on success; false otherwise
492 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
494 memcached_return_t rc= memcached_decrement(&memc, key.c_str(),
497 return (rc == MEMCACHED_SUCCESS);
502 * Add an object with the specified key and value to the server. This
503 * function returns false if the object already exists on the server.
505 * @param[in] key key of object to add
506 * @param[in] value of object to add
507 * @return true on success; false otherwise
509 bool add(const std::string &key, const std::vector<char> &value)
511 memcached_return_t rc= memcached_add(&memc, key.c_str(), key.length(),
512 &value[0], value.size(), 0, 0);
513 return (rc == MEMCACHED_SUCCESS);
517 * Add an object with the specified key and value to the server. This
518 * function returns false if the object already exists on the server. The
519 * server to add the object to is specified by the master_key parameter.
521 * @param[in[ master_key key of server to add object to
522 * @param[in] key key of object to add
523 * @param[in] value of object to add
524 * @return true on success; false otherwise
526 bool addByKey(const std::string &master_key,
527 const std::string &key,
528 const std::vector<char> &value)
530 memcached_return_t rc= memcached_add_by_key(&memc,
538 return (rc == MEMCACHED_SUCCESS);
542 * Replaces an object on the server. This method only succeeds
543 * if the object is already present on the server.
545 * @param[in] key key of object to replace
546 * @param[in[ value value to replace object with
547 * @return true on success; false otherwise
549 bool replace(const std::string &key, const std::vector<char> &value)
551 memcached_return_t rc= memcached_replace(&memc, key.c_str(), key.length(),
552 &value[0], value.size(),
554 return (rc == MEMCACHED_SUCCESS);
558 * Replaces an object on the server. This method only succeeds
559 * if the object is already present on the server. The server
560 * to replace the object on is specified by the master_key param.
562 * @param[in] master_key key of server to replace object on
563 * @param[in] key key of object to replace
564 * @param[in[ value value to replace object with
565 * @return true on success; false otherwise
567 bool replaceByKey(const std::string &master_key,
568 const std::string &key,
569 const std::vector<char> &value)
571 memcached_return_t rc= memcached_replace_by_key(&memc,
579 return (rc == MEMCACHED_SUCCESS);
583 * Places a segment of data before the last piece of data stored.
585 * @param[in] key key of object whose value we will prepend data to
586 * @param[in] value data to prepend to object's value
587 * @return true on success; false otherwise
589 bool prepend(const std::string &key, const std::vector<char> &value)
591 memcached_return_t rc= memcached_prepend(&memc, key.c_str(), key.length(),
592 &value[0], value.size(), 0, 0);
593 return (rc == MEMCACHED_SUCCESS);
597 * Places a segment of data before the last piece of data stored. The
598 * server on which the object where we will be prepending data is stored
599 * on is specified by the master_key parameter.
601 * @param[in] master_key key of server where object is stored
602 * @param[in] key key of object whose value we will prepend data to
603 * @param[in] value data to prepend to object's value
604 * @return true on success; false otherwise
606 bool prependByKey(const std::string &master_key,
607 const std::string &key,
608 const std::vector<char> &value)
610 memcached_return_t rc= memcached_prepend_by_key(&memc,
619 return (rc == MEMCACHED_SUCCESS);
623 * Places a segment of data at the end of the last piece of data stored.
625 * @param[in] key key of object whose value we will append data to
626 * @param[in] value data to append to object's value
627 * @return true on success; false otherwise
629 bool append(const std::string &key, const std::vector<char> &value)
631 memcached_return_t rc= memcached_append(&memc,
637 return (rc == MEMCACHED_SUCCESS);
641 * Places a segment of data at the end of the last piece of data stored. The
642 * server on which the object where we will be appending data is stored
643 * on is specified by the master_key parameter.
645 * @param[in] master_key key of server where object is stored
646 * @param[in] key key of object whose value we will append data to
647 * @param[in] value data to append to object's value
648 * @return true on success; false otherwise
650 bool appendByKey(const std::string &master_key,
651 const std::string &key,
652 const std::vector<char> &value)
654 memcached_return_t rc= memcached_append_by_key(&memc,
662 return (rc == MEMCACHED_SUCCESS);
666 * Overwrite data in the server as long as the cas_arg value
667 * is still the same in the server.
669 * @param[in] key key of object in server
670 * @param[in] value value to store for object in server
671 * @param[in] cas_arg "cas" value
673 bool cas(const std::string &key,
674 const std::vector<char> &value,
677 memcached_return_t rc= memcached_cas(&memc, key.c_str(), key.length(),
678 &value[0], value.size(),
680 return (rc == MEMCACHED_SUCCESS);
684 * Overwrite data in the server as long as the cas_arg value
685 * is still the same in the server. The server to use is
686 * specified by the master_key parameter.
688 * @param[in] master_key specifies server to operate on
689 * @param[in] key key of object in server
690 * @param[in] value value to store for object in server
691 * @param[in] cas_arg "cas" value
693 bool casByKey(const std::string &master_key,
694 const std::string &key,
695 const std::vector<char> &value,
698 memcached_return_t rc= memcached_cas_by_key(&memc,
706 return (rc == MEMCACHED_SUCCESS);
710 * Delete an object from the server specified by the key given.
712 * @param[in] key key of object to delete
713 * @return true on success; false otherwise
715 bool remove(const std::string &key)
717 memcached_return_t rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
718 return (rc == MEMCACHED_SUCCESS);
722 * Delete an object from the server specified by the key given.
724 * @param[in] key key of object to delete
725 * @param[in] expiration time to delete the object after
726 * @return true on success; false otherwise
728 bool remove(const std::string &key, time_t expiration)
730 memcached_return_t rc= memcached_delete(&memc,
734 return (rc == MEMCACHED_SUCCESS);
738 * Delete an object from the server specified by the key given.
740 * @param[in] master_key specifies server to remove object from
741 * @param[in] key key of object to delete
742 * @return true on success; false otherwise
744 bool removeByKey(const std::string &master_key,
745 const std::string &key)
747 memcached_return_t rc= memcached_delete_by_key(&memc,
753 return (rc == MEMCACHED_SUCCESS);
757 * Delete an object from the server specified by the key given.
759 * @param[in] master_key specifies server to remove object from
760 * @param[in] key key of object to delete
761 * @param[in] expiration time to delete the object after
762 * @return true on success; false otherwise
764 bool removeByKey(const std::string &master_key,
765 const std::string &key,
768 memcached_return_t rc= memcached_delete_by_key(&memc,
774 return (rc == MEMCACHED_SUCCESS);
778 * Wipe the contents of memcached servers.
780 * @param[in] expiration time to wait until wiping contents of
782 * @return true on success; false otherwise
784 bool flush(time_t expiration)
786 memcached_return_t rc= memcached_flush(&memc, expiration);
787 return (rc == MEMCACHED_SUCCESS);
791 * Get the library version string.
792 * @return std::string containing a copy of the library version string.
794 const std::string libVersion() const
796 const char *ver= memcached_lib_version();
797 const std::string version(ver);
802 * Retrieve memcached statistics. Populate a std::map with the retrieved
803 * stats. Each server will map to another std::map of the key:value stats.
805 * @param[out] stats_map a std::map to be populated with the memcached
807 * @return true on success; false otherwise
809 bool getStats(std::map< std::string, std::map<std::string, std::string> >
812 memcached_return_t rc;
813 memcached_stat_st *stats= memcached_stat(&memc, NULL, &rc);
815 if (rc != MEMCACHED_SUCCESS &&
816 rc != MEMCACHED_SOME_ERRORS)
821 uint32_t server_count= memcached_server_count(&memc);
824 * For each memcached server, construct a std::map for its stats and add
825 * it to the std::map of overall stats.
827 for (uint32_t x= 0; x < server_count; x++)
829 memcached_server_instance_st instance=
830 memcached_server_instance_by_position(&memc, x);
831 std::ostringstream strstm;
832 std::string server_name(memcached_server_name(instance));
833 server_name.append(":");
834 strstm << memcached_server_port(instance);
835 server_name.append(strstm.str());
837 std::map<std::string, std::string> server_stats;
841 list= memcached_stat_get_keys(&memc, &stats[x], &rc);
842 for (ptr= list; *ptr; ptr++)
844 char *value= memcached_stat_get_value(&memc, &stats[x], *ptr, &rc);
845 server_stats[*ptr]= value;
849 stats_map[server_name]= server_stats;
853 memcached_stat_free(&memc, stats);
859 std::string servers_list;
861 memcached_result_st result;