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 return memcached_success(memcached_server_add(memc, server_name.c_str(), port));
136 * Remove a server from the list of memcached servers to use.
138 * @param[in] server_name name of the server to remove
139 * @param[in] port port number of server to remove
140 * @return true on success; false otherwise
142 bool removeServer(const std::string &server_name, in_port_t port)
145 std::ostringstream strstm;
147 tmp_str.append(server_name);
150 tmp_str.append(strstm.str());
152 //memcached_return_t rc= memcached_server_remove(server);
158 * Fetches an individual value from the server. mget() must always
159 * be called before using this method.
161 * @param[in] key key of object to fetch
162 * @param[out] ret_val store returned object in this vector
163 * @return a memcached return structure
165 memcached_return_t fetch(std::string &key,
166 std::vector<char> &ret_val,
170 memcached_return_t rc;
172 memcached_result_st *result;
173 if ((result= memcached_fetch_result(memc, NULL, &rc)))
176 key.assign(memcached_result_key_value(result), memcached_result_key_length(result));
178 // Actual value, null terminated
179 ret_val.reserve(memcached_result_length(result) +1);
180 ret_val.assign(memcached_result_value(result),
181 memcached_result_value(result) +memcached_result_length(result));
184 flags= memcached_result_flags(result);
185 cas_value= memcached_result_cas(result);
187 memcached_result_free(result);
192 memcached_return_t fetch(std::string &key,
193 std::vector<char> &ret_val)
196 uint64_t cas_value= 0;
198 return fetch(key, ret_val, flags, cas_value);
202 * Fetches an individual value from the server.
204 * @param[in] key key of object whose value to get
205 * @param[out] ret_val object that is retrieved is stored in
207 * @return true on success; false otherwise
209 bool get(const std::string &key, std::vector<char> &ret_val)
212 memcached_return_t rc;
213 size_t value_length= 0;
215 char *value= memcached_get(memc, key.c_str(), key.length(),
216 &value_length, &flags, &rc);
217 if (value != NULL && ret_val.empty())
219 ret_val.reserve(value_length);
220 ret_val.assign(value, value + value_length);
229 * Fetches an individual from a server which is specified by
230 * the master_key parameter that is used for determining which
231 * server an object was stored in if key partitioning was
234 * @param[in] master_key key that specifies server object is stored on
235 * @param[in] key key of object whose value to get
236 * @param[out] ret_val object that is retrieved is stored in
238 * @return true on success; false otherwise
240 bool getByKey(const std::string &master_key,
241 const std::string &key,
242 std::vector<char> &ret_val)
245 memcached_return_t rc;
246 size_t value_length= 0;
248 char *value= memcached_get_by_key(memc,
249 master_key.c_str(), master_key.length(),
250 key.c_str(), key.length(),
251 &value_length, &flags, &rc);
254 ret_val.reserve(value_length);
255 ret_val.assign(value, value + value_length);
263 * Selects multiple keys at once. This method always
264 * works asynchronously.
266 * @param[in] keys vector of keys to select
267 * @return true if all keys are found
269 bool mget(std::vector<std::string> &keys)
271 std::vector<const char *> real_keys;
272 std::vector<size_t> key_len;
274 * Construct an array which will contain the length
275 * of each of the strings in the input vector. Also, to
276 * interface with the memcached C API, we need to convert
277 * the vector of std::string's to a vector of char *.
279 real_keys.reserve(keys.size());
280 key_len.reserve(keys.size());
282 std::vector<std::string>::iterator it= keys.begin();
284 while (it != keys.end())
286 real_keys.push_back(const_cast<char *>((*it).c_str()));
287 key_len.push_back((*it).length());
292 * If the std::vector of keys is empty then we cannot
293 * call memcached_mget as we will get undefined behavior.
295 if (not real_keys.empty())
297 return memcached_success(memcached_mget(memc, &real_keys[0], &key_len[0], real_keys.size()));
304 * Writes an object to the server. If the object already exists, it will
305 * overwrite the existing object. This method always returns true
306 * when using non-blocking mode unless a network error occurs.
308 * @param[in] key key of object to write to server
309 * @param[in] value value of object to write to server
310 * @param[in] expiration time to keep the object stored in the server for
311 * @param[in] flags flags to store with the object
312 * @return true on succcess; false otherwise
314 bool set(const std::string &key,
315 const std::vector<char> &value,
319 memcached_return_t rc= memcached_set(memc,
320 key.c_str(), key.length(),
321 &value[0], value.size(),
323 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
327 * Writes an object to a server specified by the master_key parameter.
328 * If the object already exists, it will overwrite the existing object.
330 * @param[in] master_key key that specifies server to write to
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 setByKey(const std::string &master_key,
338 const std::string &key,
339 const std::vector<char> &value,
343 return memcached_success(memcached_set_by_key(memc, master_key.c_str(),
345 key.c_str(), key.length(),
346 &value[0], value.size(),
352 * Writes a list of objects to the server. Objects are specified by
353 * 2 vectors - 1 vector of keys and 1 vector of values.
355 * @param[in] keys vector of keys of objects to write to server
356 * @param[in] values vector of values of objects to write to server
357 * @param[in] expiration time to keep the objects stored in server for
358 * @param[in] flags flags to store with the objects
359 * @return true on success; false otherwise
361 bool setAll(std::vector<std::string> &keys,
362 std::vector< std::vector<char> *> &values,
367 std::vector<std::string>::iterator key_it= keys.begin();
368 std::vector< std::vector<char> *>::iterator val_it= values.begin();
369 while (key_it != keys.end())
371 retval= set((*key_it), *(*val_it), expiration, flags);
383 * Writes a list of objects to the server. Objects are specified by
384 * a map of keys to values.
386 * @param[in] key_value_map map of keys and values to store in server
387 * @param[in] expiration time to keep the objects stored in server for
388 * @param[in] flags flags to store with the objects
389 * @return true on success; false otherwise
391 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
396 std::map<const std::string, std::vector<char> >::iterator it= key_value_map.begin();
398 while (it != key_value_map.end())
400 retval= set(it->first, it->second, expiration, flags);
403 // We should tell the user what the key that failed was
412 * Increment the value of the object associated with the specified
413 * key by the offset given. The resulting value is saved in the value
416 * @param[in] key key of object in server whose value to increment
417 * @param[in] offset amount to increment object's value by
418 * @param[out] value store the result of the increment here
419 * @return true on success; false otherwise
421 bool increment(const std::string &key, uint32_t offset, uint64_t *value)
423 return memcached_success(memcached_increment(memc, key.c_str(), key.length(), offset, value));
427 * Decrement the value of the object associated with the specified
428 * key by the offset given. The resulting value is saved in the value
431 * @param[in] key key of object in server whose value to decrement
432 * @param[in] offset amount to increment object's value by
433 * @param[out] value store the result of the decrement here
434 * @return true on success; false otherwise
436 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
438 return memcached_success(memcached_decrement(memc, key.c_str(),
445 * Add an object with the specified key and value to the server. This
446 * function returns false if the object already exists on the server.
448 * @param[in] key key of object to add
449 * @param[in] value of object to add
450 * @return true on success; false otherwise
452 bool add(const std::string &key, const std::vector<char> &value)
454 return memcached_success(memcached_add(memc, key.c_str(), key.length(),
455 &value[0], value.size(), 0, 0));
459 * Add an object with the specified key and value to the server. This
460 * function returns false if the object already exists on the server. The
461 * server to add the object to is specified by the master_key parameter.
463 * @param[in[ master_key key of server to add object to
464 * @param[in] key key of object to add
465 * @param[in] value of object to add
466 * @return true on success; false otherwise
468 bool addByKey(const std::string &master_key,
469 const std::string &key,
470 const std::vector<char> &value)
472 return memcached_success(memcached_add_by_key(memc,
483 * Replaces an object on the server. This method only succeeds
484 * if the object is already present on the server.
486 * @param[in] key key of object to replace
487 * @param[in[ value value to replace object with
488 * @return true on success; false otherwise
490 bool replace(const std::string &key, const std::vector<char> &value)
492 return memcached_success(memcached_replace(memc, key.c_str(), key.length(),
493 &value[0], value.size(),
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 return memcached_success(memcached_replace_by_key(memc,
522 * Places a segment of data before the last piece of data stored.
524 * @param[in] key key of object whose value we will prepend data to
525 * @param[in] value data to prepend to object's value
526 * @return true on success; false otherwise
528 bool prepend(const std::string &key, const std::vector<char> &value)
530 return memcached_success(memcached_prepend(memc, key.c_str(), key.length(),
531 &value[0], value.size(), 0, 0));
535 * Places a segment of data before the last piece of data stored. The
536 * server on which the object where we will be prepending data is stored
537 * on is specified by the master_key parameter.
539 * @param[in] master_key key of server where object is stored
540 * @param[in] key key of object whose value we will prepend data to
541 * @param[in] value data to prepend to object's value
542 * @return true on success; false otherwise
544 bool prependByKey(const std::string &master_key,
545 const std::string &key,
546 const std::vector<char> &value)
548 return memcached_success(memcached_prepend_by_key(memc,
560 * Places a segment of data at the end of the last piece of data stored.
562 * @param[in] key key of object whose value we will append data to
563 * @param[in] value data to append to object's value
564 * @return true on success; false otherwise
566 bool append(const std::string &key, const std::vector<char> &value)
568 return memcached_success(memcached_append(memc,
577 * Places a segment of data at the end of the last piece of data stored. The
578 * server on which the object where we will be appending data is stored
579 * on is specified by the master_key parameter.
581 * @param[in] master_key key of server where object is stored
582 * @param[in] key key of object whose value we will append data to
583 * @param[in] value data to append to object's value
584 * @return true on success; false otherwise
586 bool appendByKey(const std::string &master_key,
587 const std::string &key,
588 const std::vector<char> &value)
590 return memcached_success(memcached_append_by_key(memc,
601 * Overwrite data in the server as long as the cas_arg value
602 * is still the same in the server.
604 * @param[in] key key of object in server
605 * @param[in] value value to store for object in server
606 * @param[in] cas_arg "cas" value
608 bool cas(const std::string &key,
609 const std::vector<char> &value,
612 return memcached_success(memcached_cas(memc, key.c_str(), key.length(),
613 &value[0], value.size(),
618 * Overwrite data in the server as long as the cas_arg value
619 * is still the same in the server. The server to use is
620 * specified by the master_key parameter.
622 * @param[in] master_key specifies server to operate on
623 * @param[in] key key of object in server
624 * @param[in] value value to store for object in server
625 * @param[in] cas_arg "cas" value
627 bool casByKey(const std::string &master_key,
628 const std::string &key,
629 const std::vector<char> &value,
632 return memcached_success(memcached_cas_by_key(memc,
643 * Delete an object from the server specified by the key given.
645 * @param[in] key key of object to delete
646 * @return true on success; false otherwise
648 bool remove(const std::string &key)
650 return memcached_success(memcached_delete(memc, key.c_str(), key.length(), 0));
654 * Delete an object from the server specified by the key given.
656 * @param[in] key key of object to delete
657 * @param[in] expiration time to delete the object after
658 * @return true on success; false otherwise
660 bool remove(const std::string &key, time_t expiration)
662 return memcached_success(memcached_delete(memc,
669 * Delete an object from the server specified by the key given.
671 * @param[in] master_key specifies server to remove object from
672 * @param[in] key key of object to delete
673 * @return true on success; false otherwise
675 bool removeByKey(const std::string &master_key,
676 const std::string &key)
678 return memcached_success(memcached_delete_by_key(memc,
687 * Delete an object from the server specified by the key given.
689 * @param[in] master_key specifies server to remove object from
690 * @param[in] key key of object to delete
691 * @param[in] expiration time to delete the object after
692 * @return true on success; false otherwise
694 bool removeByKey(const std::string &master_key,
695 const std::string &key,
698 return memcached_success(memcached_delete_by_key(memc,
707 * Wipe the contents of memcached servers.
709 * @param[in] expiration time to wait until wiping contents of
711 * @return true on success; false otherwise
713 bool flush(time_t expiration= 0)
715 return memcached_success(memcached_flush(memc, expiration));
719 * Get the library version string.
720 * @return std::string containing a copy of the library version string.
722 const std::string libVersion() const
724 const char *ver= memcached_lib_version();
725 const std::string version(ver);
730 * Retrieve memcached statistics. Populate a std::map with the retrieved
731 * stats. Each server will map to another std::map of the key:value stats.
733 * @param[out] stats_map a std::map to be populated with the memcached
735 * @return true on success; false otherwise
737 bool getStats(std::map< std::string, std::map<std::string, std::string> >
740 memcached_return_t rc;
741 memcached_stat_st *stats= memcached_stat(memc, NULL, &rc);
743 if (rc != MEMCACHED_SUCCESS &&
744 rc != MEMCACHED_SOME_ERRORS)
749 uint32_t server_count= memcached_server_count(memc);
752 * For each memcached server, construct a std::map for its stats and add
753 * it to the std::map of overall stats.
755 for (uint32_t x= 0; x < server_count; x++)
757 memcached_server_instance_st instance=
758 memcached_server_instance_by_position(memc, x);
759 std::ostringstream strstm;
760 std::string server_name(memcached_server_name(instance));
761 server_name.append(":");
762 strstm << memcached_server_port(instance);
763 server_name.append(strstm.str());
765 std::map<std::string, std::string> server_stats;
769 list= memcached_stat_get_keys(memc, &stats[x], &rc);
770 for (ptr= list; *ptr; ptr++)
772 char *value= memcached_stat_get_value(memc, &stats[x], *ptr, &rc);
773 server_stats[*ptr]= value;
777 stats_map[server_name]= server_stats;
781 memcached_stat_free(memc, stats);