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).
40 memc= memcached("", 0);
43 Memcache(const std::string &config)
45 memc= memcached(config.c_str(), config.size());
48 Memcache(const std::string &hostname, in_port_t port)
50 memc= memcached("", 0);
52 memcached_server_add(memc, hostname.c_str(), port);
55 Memcache(memcached_st *clone)
57 memc= memcached_clone(NULL, clone);
60 Memcache(const Memcache &rhs)
62 memc= memcached_clone(NULL, rhs.getImpl());
65 Memcache &operator=(const Memcache &rhs)
70 memc= memcached_clone(NULL, rhs.getImpl());
82 * Get the internal memcached_st *
84 const memcached_st *getImpl() const
90 * Return an error string for the given return structure.
92 * @param[in] rc a memcached_return_t structure
93 * @return error string corresponding to given return code in the library.
95 const std::string getError(memcached_return_t rc) const
97 /* first parameter to strerror is unused */
98 return memcached_strerror(NULL, rc);
102 bool setBehavior(memcached_behavior_t flag, uint64_t data)
104 return (memcached_success(memcached_behavior_set(memc, flag, data)));
107 uint64_t getBehavior(memcached_behavior_t flag)
109 return memcached_behavior_get(memc, flag);
113 * Configure the memcache object
115 * @param[in] in_config configuration
116 * @return true on success; false otherwise
118 bool configure(const std::string &configuration)
120 return (memcached_success(memcached_parse_configuration(memc, configuration.c_str(), configuration.size())));
124 * Add a server to the list of memcached servers to use.
126 * @param[in] server_name name of the server to add
127 * @param[in] port port number of server to add
128 * @return true on success; false otherwise
130 bool addServer(const std::string &server_name, in_port_t port)
132 memcached_return_t rc;
134 rc= memcached_server_add(memc, server_name.c_str(), port);
136 return (rc == MEMCACHED_SUCCESS);
140 * Remove a server from the list of memcached servers to use.
142 * @param[in] server_name name of the server to remove
143 * @param[in] port port number of server to remove
144 * @return true on success; false otherwise
146 bool removeServer(const std::string &server_name, in_port_t port)
149 std::ostringstream strstm;
151 tmp_str.append(server_name);
154 tmp_str.append(strstm.str());
156 //memcached_return_t rc= memcached_server_remove(server);
162 * Fetches an individual value from the server. mget() must always
163 * be called before using this method.
165 * @param[in] key key of object to fetch
166 * @param[out] ret_val store returned object in this vector
167 * @return a memcached return structure
169 memcached_return_t fetch(std::string &key,
170 std::vector<char> &ret_val)
172 char ret_key[MEMCACHED_MAX_KEY];
173 size_t value_length= 0;
174 size_t key_length= 0;
175 memcached_return_t rc;
177 char *value= memcached_fetch(memc, ret_key, &key_length,
178 &value_length, &flags, &rc);
179 if (value && ret_val.empty())
181 ret_val.reserve(value_length);
182 ret_val.assign(value, value + value_length);
183 key.assign(ret_key, key_length);
195 * Fetches an individual value from the server.
197 * @param[in] key key of object whose value to get
198 * @param[out] ret_val object that is retrieved is stored in
200 * @return true on success; false otherwise
202 bool get(const std::string &key, std::vector<char> &ret_val)
205 memcached_return_t rc;
206 size_t value_length= 0;
208 char *value= memcached_get(memc, key.c_str(), key.length(),
209 &value_length, &flags, &rc);
210 if (value != NULL && ret_val.empty())
212 ret_val.reserve(value_length);
213 ret_val.assign(value, value + value_length);
221 * Fetches an individual from a server which is specified by
222 * the master_key parameter that is used for determining which
223 * server an object was stored in if key partitioning was
226 * @param[in] master_key key that specifies server object is stored on
227 * @param[in] key key of object whose value to get
228 * @param[out] ret_val object that is retrieved is stored in
230 * @return true on success; false otherwise
232 bool getByKey(const std::string &master_key,
233 const std::string &key,
234 std::vector<char> &ret_val)
237 memcached_return_t rc;
238 size_t value_length= 0;
240 char *value= memcached_get_by_key(memc,
241 master_key.c_str(), master_key.length(),
242 key.c_str(), key.length(),
243 &value_length, &flags, &rc);
246 ret_val.reserve(value_length);
247 ret_val.assign(value, value + value_length);
255 * Selects multiple keys at once. This method always
256 * works asynchronously.
258 * @param[in] keys vector of keys to select
259 * @return true if all keys are found
261 bool mget(std::vector<std::string> &keys)
263 std::vector<const char *> real_keys;
264 std::vector<size_t> key_len;
266 * Construct an array which will contain the length
267 * of each of the strings in the input vector. Also, to
268 * interface with the memcached C API, we need to convert
269 * the vector of std::string's to a vector of char *.
271 real_keys.reserve(keys.size());
272 key_len.reserve(keys.size());
274 std::vector<std::string>::iterator it= keys.begin();
276 while (it != keys.end())
278 real_keys.push_back(const_cast<char *>((*it).c_str()));
279 key_len.push_back((*it).length());
284 * If the std::vector of keys is empty then we cannot
285 * call memcached_mget as we will get undefined behavior.
287 if (! real_keys.empty())
289 memcached_return_t rc= memcached_mget(memc, &real_keys[0], &key_len[0], real_keys.size());
290 return (rc == MEMCACHED_SUCCESS);
297 * Writes an object to the server. If the object already exists, it will
298 * overwrite the existing object. This method always returns true
299 * when using non-blocking mode unless a network error occurs.
301 * @param[in] key key of object to write to server
302 * @param[in] value value of object to write to server
303 * @param[in] expiration time to keep the object stored in the server for
304 * @param[in] flags flags to store with the object
305 * @return true on succcess; false otherwise
307 bool set(const std::string &key,
308 const std::vector<char> &value,
312 memcached_return_t rc= memcached_set(memc,
313 key.c_str(), key.length(),
314 &value[0], value.size(),
316 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
320 * Writes an object to a server specified by the master_key parameter.
321 * If the object already exists, it will overwrite the existing object.
323 * @param[in] master_key key that specifies server to write to
324 * @param[in] key key of object to write to server
325 * @param[in] value value of object to write to server
326 * @param[in] expiration time to keep the object stored in the server for
327 * @param[in] flags flags to store with the object
328 * @return true on succcess; false otherwise
330 bool setByKey(const std::string &master_key,
331 const std::string &key,
332 const std::vector<char> &value,
336 memcached_return_t rc= memcached_set_by_key(memc, master_key.c_str(),
338 key.c_str(), key.length(),
339 &value[0], value.size(),
342 return (rc == MEMCACHED_SUCCESS);
346 * Writes a list of objects to the server. Objects are specified by
347 * 2 vectors - 1 vector of keys and 1 vector of values.
349 * @param[in] keys vector of keys of objects to write to server
350 * @param[in] values vector of values of objects to write to server
351 * @param[in] expiration time to keep the objects stored in server for
352 * @param[in] flags flags to store with the objects
353 * @return true on success; false otherwise
355 bool setAll(std::vector<std::string> &keys,
356 std::vector< std::vector<char> *> &values,
361 std::vector<std::string>::iterator key_it= keys.begin();
362 std::vector< std::vector<char> *>::iterator val_it= values.begin();
363 while (key_it != keys.end())
365 retval= set((*key_it), *(*val_it), expiration, flags);
377 * Writes a list of objects to the server. Objects are specified by
378 * a map of keys to values.
380 * @param[in] key_value_map map of keys and values to store in server
381 * @param[in] expiration time to keep the objects stored in server for
382 * @param[in] flags flags to store with the objects
383 * @return true on success; false otherwise
385 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
390 std::map<const std::string, std::vector<char> >::iterator it= key_value_map.begin();
392 while (it != key_value_map.end())
394 retval= set(it->first, it->second, expiration, flags);
397 // We should tell the user what the key that failed was
406 * Increment the value of the object associated with the specified
407 * key by the offset given. The resulting value is saved in the value
410 * @param[in] key key of object in server whose value to increment
411 * @param[in] offset amount to increment object's value by
412 * @param[out] value store the result of the increment here
413 * @return true on success; false otherwise
415 bool increment(const std::string &key, uint32_t offset, uint64_t *value)
417 memcached_return_t rc= memcached_increment(memc, key.c_str(), key.length(),
419 return (rc == MEMCACHED_SUCCESS);
423 * Decrement the value of the object associated with the specified
424 * key by the offset given. The resulting value is saved in the value
427 * @param[in] key key of object in server whose value to decrement
428 * @param[in] offset amount to increment object's value by
429 * @param[out] value store the result of the decrement here
430 * @return true on success; false otherwise
432 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
434 memcached_return_t rc= memcached_decrement(memc, key.c_str(),
437 return (rc == MEMCACHED_SUCCESS);
442 * Add an object with the specified key and value to the server. This
443 * function returns false if the object already exists on the server.
445 * @param[in] key key of object to add
446 * @param[in] value of object to add
447 * @return true on success; false otherwise
449 bool add(const std::string &key, const std::vector<char> &value)
451 memcached_return_t rc= memcached_add(memc, key.c_str(), key.length(),
452 &value[0], value.size(), 0, 0);
453 return (rc == MEMCACHED_SUCCESS);
457 * Add an object with the specified key and value to the server. This
458 * function returns false if the object already exists on the server. The
459 * server to add the object to is specified by the master_key parameter.
461 * @param[in[ master_key key of server to add object to
462 * @param[in] key key of object to add
463 * @param[in] value of object to add
464 * @return true on success; false otherwise
466 bool addByKey(const std::string &master_key,
467 const std::string &key,
468 const std::vector<char> &value)
470 memcached_return_t rc= memcached_add_by_key(memc,
478 return (rc == MEMCACHED_SUCCESS);
482 * Replaces an object on the server. This method only succeeds
483 * if the object is already present on the server.
485 * @param[in] key key of object to replace
486 * @param[in[ value value to replace object with
487 * @return true on success; false otherwise
489 bool replace(const std::string &key, const std::vector<char> &value)
491 memcached_return_t rc= memcached_replace(memc, key.c_str(), key.length(),
492 &value[0], value.size(),
494 return (rc == MEMCACHED_SUCCESS);
498 * Replaces an object on the server. This method only succeeds
499 * if the object is already present on the server. The server
500 * to replace the object on is specified by the master_key param.
502 * @param[in] master_key key of server to replace object on
503 * @param[in] key key of object to replace
504 * @param[in[ value value to replace object with
505 * @return true on success; false otherwise
507 bool replaceByKey(const std::string &master_key,
508 const std::string &key,
509 const std::vector<char> &value)
511 memcached_return_t rc= memcached_replace_by_key(memc,
519 return (rc == MEMCACHED_SUCCESS);
523 * Places a segment of data before the last piece of data stored.
525 * @param[in] key key of object whose value we will prepend data to
526 * @param[in] value data to prepend to object's value
527 * @return true on success; false otherwise
529 bool prepend(const std::string &key, const std::vector<char> &value)
531 memcached_return_t rc= memcached_prepend(memc, key.c_str(), key.length(),
532 &value[0], value.size(), 0, 0);
533 return (rc == MEMCACHED_SUCCESS);
537 * Places a segment of data before the last piece of data stored. The
538 * server on which the object where we will be prepending data is stored
539 * on is specified by the master_key parameter.
541 * @param[in] master_key key of server where object is stored
542 * @param[in] key key of object whose value we will prepend data to
543 * @param[in] value data to prepend to object's value
544 * @return true on success; false otherwise
546 bool prependByKey(const std::string &master_key,
547 const std::string &key,
548 const std::vector<char> &value)
550 memcached_return_t rc= memcached_prepend_by_key(memc,
559 return (rc == MEMCACHED_SUCCESS);
563 * Places a segment of data at the end of the last piece of data stored.
565 * @param[in] key key of object whose value we will append data to
566 * @param[in] value data to append to object's value
567 * @return true on success; false otherwise
569 bool append(const std::string &key, const std::vector<char> &value)
571 memcached_return_t rc= memcached_append(memc,
577 return (rc == MEMCACHED_SUCCESS);
581 * Places a segment of data at the end of the last piece of data stored. The
582 * server on which the object where we will be appending data is stored
583 * on is specified by the master_key parameter.
585 * @param[in] master_key key of server where object is stored
586 * @param[in] key key of object whose value we will append data to
587 * @param[in] value data to append to object's value
588 * @return true on success; false otherwise
590 bool appendByKey(const std::string &master_key,
591 const std::string &key,
592 const std::vector<char> &value)
594 memcached_return_t rc= memcached_append_by_key(memc,
602 return (rc == MEMCACHED_SUCCESS);
606 * Overwrite data in the server as long as the cas_arg value
607 * is still the same in the server.
609 * @param[in] key key of object in server
610 * @param[in] value value to store for object in server
611 * @param[in] cas_arg "cas" value
613 bool cas(const std::string &key,
614 const std::vector<char> &value,
617 memcached_return_t rc= memcached_cas(memc, key.c_str(), key.length(),
618 &value[0], value.size(),
620 return (rc == MEMCACHED_SUCCESS);
624 * Overwrite data in the server as long as the cas_arg value
625 * is still the same in the server. The server to use is
626 * specified by the master_key parameter.
628 * @param[in] master_key specifies server to operate on
629 * @param[in] key key of object in server
630 * @param[in] value value to store for object in server
631 * @param[in] cas_arg "cas" value
633 bool casByKey(const std::string &master_key,
634 const std::string &key,
635 const std::vector<char> &value,
638 memcached_return_t rc= memcached_cas_by_key(memc,
646 return (rc == MEMCACHED_SUCCESS);
650 * Delete an object from the server specified by the key given.
652 * @param[in] key key of object to delete
653 * @return true on success; false otherwise
655 bool remove(const std::string &key)
657 memcached_return_t rc= memcached_delete(memc, key.c_str(), key.length(), 0);
658 return (rc == MEMCACHED_SUCCESS);
662 * Delete an object from the server specified by the key given.
664 * @param[in] key key of object to delete
665 * @param[in] expiration time to delete the object after
666 * @return true on success; false otherwise
668 bool remove(const std::string &key, time_t expiration)
670 memcached_return_t rc= memcached_delete(memc,
674 return (rc == MEMCACHED_SUCCESS);
678 * Delete an object from the server specified by the key given.
680 * @param[in] master_key specifies server to remove object from
681 * @param[in] key key of object to delete
682 * @return true on success; false otherwise
684 bool removeByKey(const std::string &master_key,
685 const std::string &key)
687 memcached_return_t rc= memcached_delete_by_key(memc,
693 return (rc == MEMCACHED_SUCCESS);
697 * Delete an object from the server specified by the key given.
699 * @param[in] master_key specifies server to remove object from
700 * @param[in] key key of object to delete
701 * @param[in] expiration time to delete the object after
702 * @return true on success; false otherwise
704 bool removeByKey(const std::string &master_key,
705 const std::string &key,
708 memcached_return_t rc= memcached_delete_by_key(memc,
714 return (rc == MEMCACHED_SUCCESS);
718 * Wipe the contents of memcached servers.
720 * @param[in] expiration time to wait until wiping contents of
722 * @return true on success; false otherwise
724 bool flush(time_t expiration)
726 memcached_return_t rc= memcached_flush(memc, expiration);
727 return (rc == MEMCACHED_SUCCESS);
731 * Get the library version string.
732 * @return std::string containing a copy of the library version string.
734 const std::string libVersion() const
736 const char *ver= memcached_lib_version();
737 const std::string version(ver);
742 * Retrieve memcached statistics. Populate a std::map with the retrieved
743 * stats. Each server will map to another std::map of the key:value stats.
745 * @param[out] stats_map a std::map to be populated with the memcached
747 * @return true on success; false otherwise
749 bool getStats(std::map< std::string, std::map<std::string, std::string> >
752 memcached_return_t rc;
753 memcached_stat_st *stats= memcached_stat(memc, NULL, &rc);
755 if (rc != MEMCACHED_SUCCESS &&
756 rc != MEMCACHED_SOME_ERRORS)
761 uint32_t server_count= memcached_server_count(memc);
764 * For each memcached server, construct a std::map for its stats and add
765 * it to the std::map of overall stats.
767 for (uint32_t x= 0; x < server_count; x++)
769 memcached_server_instance_st instance=
770 memcached_server_instance_by_position(memc, x);
771 std::ostringstream strstm;
772 std::string server_name(memcached_server_name(instance));
773 server_name.append(":");
774 strstm << memcached_server_port(instance);
775 server_name.append(strstm.str());
777 std::map<std::string, std::string> server_stats;
781 list= memcached_stat_get_keys(memc, &stats[x], &rc);
782 for (ptr= list; *ptr; ptr++)
784 char *value= memcached_stat_get_value(memc, &stats[x], *ptr, &rc);
785 server_stats[*ptr]= value;
789 stats_map[server_name]= server_stats;
793 memcached_stat_free(memc, stats);