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 memcached_st *new_memc= memcached(configuration.c_str(), configuration.size());
124 memcached_free(memc);
134 * Add a server to the list of memcached servers to use.
136 * @param[in] server_name name of the server to add
137 * @param[in] port port number of server to add
138 * @return true on success; false otherwise
140 bool addServer(const std::string &server_name, in_port_t port)
142 return memcached_success(memcached_server_add(memc, server_name.c_str(), port));
146 * Remove a server from the list of memcached servers to use.
148 * @param[in] server_name name of the server to remove
149 * @param[in] port port number of server to remove
150 * @return true on success; false otherwise
152 bool removeServer(const std::string &server_name, in_port_t port)
155 std::ostringstream strstm;
157 tmp_str.append(server_name);
160 tmp_str.append(strstm.str());
162 //memcached_return_t rc= memcached_server_remove(server);
168 * Fetches an individual value from the server. mget() must always
169 * be called before using this method.
171 * @param[in] key key of object to fetch
172 * @param[out] ret_val store returned object in this vector
173 * @return a memcached return structure
175 memcached_return_t fetch(std::string &key,
176 std::vector<char> &ret_val,
180 memcached_return_t rc;
182 memcached_result_st *result;
183 if ((result= memcached_fetch_result(memc, NULL, &rc)))
186 key.assign(memcached_result_key_value(result), memcached_result_key_length(result));
188 // Actual value, null terminated
189 ret_val.reserve(memcached_result_length(result) +1);
190 ret_val.assign(memcached_result_value(result),
191 memcached_result_value(result) +memcached_result_length(result));
194 flags= memcached_result_flags(result);
195 cas_value= memcached_result_cas(result);
197 memcached_result_free(result);
202 memcached_return_t fetch(std::string &key,
203 std::vector<char> &ret_val)
206 uint64_t cas_value= 0;
208 return fetch(key, ret_val, flags, cas_value);
212 * Fetches an individual value from the server.
214 * @param[in] key key of object whose value to get
215 * @param[out] ret_val object that is retrieved is stored in
217 * @return true on success; false otherwise
219 bool get(const std::string &key, std::vector<char> &ret_val)
222 memcached_return_t rc;
223 size_t value_length= 0;
225 char *value= memcached_get(memc, key.c_str(), key.length(),
226 &value_length, &flags, &rc);
227 if (value != NULL && ret_val.empty())
229 ret_val.reserve(value_length);
230 ret_val.assign(value, value + value_length);
239 * Fetches an individual from a server which is specified by
240 * the master_key parameter that is used for determining which
241 * server an object was stored in if key partitioning was
244 * @param[in] master_key key that specifies server object is stored on
245 * @param[in] key key of object whose value to get
246 * @param[out] ret_val object that is retrieved is stored in
248 * @return true on success; false otherwise
250 bool getByKey(const std::string &master_key,
251 const std::string &key,
252 std::vector<char> &ret_val)
255 memcached_return_t rc;
256 size_t value_length= 0;
258 char *value= memcached_get_by_key(memc,
259 master_key.c_str(), master_key.length(),
260 key.c_str(), key.length(),
261 &value_length, &flags, &rc);
264 ret_val.reserve(value_length);
265 ret_val.assign(value, value + value_length);
273 * Selects multiple keys at once. This method always
274 * works asynchronously.
276 * @param[in] keys vector of keys to select
277 * @return true if all keys are found
279 bool mget(std::vector<std::string> &keys)
281 std::vector<const char *> real_keys;
282 std::vector<size_t> key_len;
284 * Construct an array which will contain the length
285 * of each of the strings in the input vector. Also, to
286 * interface with the memcached C API, we need to convert
287 * the vector of std::string's to a vector of char *.
289 real_keys.reserve(keys.size());
290 key_len.reserve(keys.size());
292 std::vector<std::string>::iterator it= keys.begin();
294 while (it != keys.end())
296 real_keys.push_back(const_cast<char *>((*it).c_str()));
297 key_len.push_back((*it).length());
302 * If the std::vector of keys is empty then we cannot
303 * call memcached_mget as we will get undefined behavior.
305 if (not real_keys.empty())
307 return memcached_success(memcached_mget(memc, &real_keys[0], &key_len[0], real_keys.size()));
314 * Writes an object to the server. If the object already exists, it will
315 * overwrite the existing object. This method always returns true
316 * when using non-blocking mode unless a network error occurs.
318 * @param[in] key key of object to write to server
319 * @param[in] value value of object to write to server
320 * @param[in] expiration time to keep the object stored in the server for
321 * @param[in] flags flags to store with the object
322 * @return true on succcess; false otherwise
324 bool set(const std::string &key,
325 const std::vector<char> &value,
329 memcached_return_t rc= memcached_set(memc,
330 key.c_str(), key.length(),
331 &value[0], value.size(),
333 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
337 * Writes an object to a server specified by the master_key parameter.
338 * If the object already exists, it will overwrite the existing object.
340 * @param[in] master_key key that specifies server to write to
341 * @param[in] key key of object to write to server
342 * @param[in] value value of object to write to server
343 * @param[in] expiration time to keep the object stored in the server for
344 * @param[in] flags flags to store with the object
345 * @return true on succcess; false otherwise
347 bool setByKey(const std::string &master_key,
348 const std::string &key,
349 const std::vector<char> &value,
353 return memcached_success(memcached_set_by_key(memc, master_key.c_str(),
355 key.c_str(), key.length(),
356 &value[0], value.size(),
362 * Writes a list of objects to the server. Objects are specified by
363 * 2 vectors - 1 vector of keys and 1 vector of values.
365 * @param[in] keys vector of keys of objects to write to server
366 * @param[in] values vector of values of objects to write to server
367 * @param[in] expiration time to keep the objects stored in server for
368 * @param[in] flags flags to store with the objects
369 * @return true on success; false otherwise
371 bool setAll(std::vector<std::string> &keys,
372 std::vector< std::vector<char> *> &values,
377 std::vector<std::string>::iterator key_it= keys.begin();
378 std::vector< std::vector<char> *>::iterator val_it= values.begin();
379 while (key_it != keys.end())
381 retval= set((*key_it), *(*val_it), expiration, flags);
393 * Writes a list of objects to the server. Objects are specified by
394 * a map of keys to values.
396 * @param[in] key_value_map map of keys and values to store in server
397 * @param[in] expiration time to keep the objects stored in server for
398 * @param[in] flags flags to store with the objects
399 * @return true on success; false otherwise
401 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
406 std::map<const std::string, std::vector<char> >::iterator it= key_value_map.begin();
408 while (it != key_value_map.end())
410 retval= set(it->first, it->second, expiration, flags);
413 // We should tell the user what the key that failed was
422 * Increment the value of the object associated with the specified
423 * key by the offset given. The resulting value is saved in the value
426 * @param[in] key key of object in server whose value to increment
427 * @param[in] offset amount to increment object's value by
428 * @param[out] value store the result of the increment here
429 * @return true on success; false otherwise
431 bool increment(const std::string &key, uint32_t offset, uint64_t *value)
433 return memcached_success(memcached_increment(memc, key.c_str(), key.length(), offset, value));
437 * Decrement the value of the object associated with the specified
438 * key by the offset given. The resulting value is saved in the value
441 * @param[in] key key of object in server whose value to decrement
442 * @param[in] offset amount to increment object's value by
443 * @param[out] value store the result of the decrement here
444 * @return true on success; false otherwise
446 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
448 return memcached_success(memcached_decrement(memc, key.c_str(),
455 * Add an object with the specified key and value to the server. This
456 * function returns false if the object already exists on the server.
458 * @param[in] key key of object to add
459 * @param[in] value of object to add
460 * @return true on success; false otherwise
462 bool add(const std::string &key, const std::vector<char> &value)
464 return memcached_success(memcached_add(memc, key.c_str(), key.length(),
465 &value[0], value.size(), 0, 0));
469 * Add an object with the specified key and value to the server. This
470 * function returns false if the object already exists on the server. The
471 * server to add the object to is specified by the master_key parameter.
473 * @param[in[ master_key key of server to add object to
474 * @param[in] key key of object to add
475 * @param[in] value of object to add
476 * @return true on success; false otherwise
478 bool addByKey(const std::string &master_key,
479 const std::string &key,
480 const std::vector<char> &value)
482 return memcached_success(memcached_add_by_key(memc,
493 * Replaces an object on the server. This method only succeeds
494 * if the object is already present on the server.
496 * @param[in] key key of object to replace
497 * @param[in[ value value to replace object with
498 * @return true on success; false otherwise
500 bool replace(const std::string &key, const std::vector<char> &value)
502 return memcached_success(memcached_replace(memc, key.c_str(), key.length(),
503 &value[0], value.size(),
508 * Replaces an object on the server. This method only succeeds
509 * if the object is already present on the server. The server
510 * to replace the object on is specified by the master_key param.
512 * @param[in] master_key key of server to replace object on
513 * @param[in] key key of object to replace
514 * @param[in[ value value to replace object with
515 * @return true on success; false otherwise
517 bool replaceByKey(const std::string &master_key,
518 const std::string &key,
519 const std::vector<char> &value)
521 return memcached_success(memcached_replace_by_key(memc,
532 * Places a segment of data before the last piece of data stored.
534 * @param[in] key key of object whose value we will prepend data to
535 * @param[in] value data to prepend to object's value
536 * @return true on success; false otherwise
538 bool prepend(const std::string &key, const std::vector<char> &value)
540 return memcached_success(memcached_prepend(memc, key.c_str(), key.length(),
541 &value[0], value.size(), 0, 0));
545 * Places a segment of data before the last piece of data stored. The
546 * server on which the object where we will be prepending data is stored
547 * on is specified by the master_key parameter.
549 * @param[in] master_key key of server where object is stored
550 * @param[in] key key of object whose value we will prepend data to
551 * @param[in] value data to prepend to object's value
552 * @return true on success; false otherwise
554 bool prependByKey(const std::string &master_key,
555 const std::string &key,
556 const std::vector<char> &value)
558 return memcached_success(memcached_prepend_by_key(memc,
570 * Places a segment of data at the end of the last piece of data stored.
572 * @param[in] key key of object whose value we will append data to
573 * @param[in] value data to append to object's value
574 * @return true on success; false otherwise
576 bool append(const std::string &key, const std::vector<char> &value)
578 return memcached_success(memcached_append(memc,
587 * Places a segment of data at the end of the last piece of data stored. The
588 * server on which the object where we will be appending data is stored
589 * on is specified by the master_key parameter.
591 * @param[in] master_key key of server where object is stored
592 * @param[in] key key of object whose value we will append data to
593 * @param[in] value data to append to object's value
594 * @return true on success; false otherwise
596 bool appendByKey(const std::string &master_key,
597 const std::string &key,
598 const std::vector<char> &value)
600 return memcached_success(memcached_append_by_key(memc,
611 * Overwrite data in the server as long as the cas_arg value
612 * is still the same in the server.
614 * @param[in] key key of object in server
615 * @param[in] value value to store for object in server
616 * @param[in] cas_arg "cas" value
618 bool cas(const std::string &key,
619 const std::vector<char> &value,
622 return memcached_success(memcached_cas(memc, key.c_str(), key.length(),
623 &value[0], value.size(),
628 * Overwrite data in the server as long as the cas_arg value
629 * is still the same in the server. The server to use is
630 * specified by the master_key parameter.
632 * @param[in] master_key specifies server to operate on
633 * @param[in] key key of object in server
634 * @param[in] value value to store for object in server
635 * @param[in] cas_arg "cas" value
637 bool casByKey(const std::string &master_key,
638 const std::string &key,
639 const std::vector<char> &value,
642 return memcached_success(memcached_cas_by_key(memc,
653 * Delete an object from the server specified by the key given.
655 * @param[in] key key of object to delete
656 * @return true on success; false otherwise
658 bool remove(const std::string &key)
660 return memcached_success(memcached_delete(memc, key.c_str(), key.length(), 0));
664 * Delete an object from the server specified by the key given.
666 * @param[in] key key of object to delete
667 * @param[in] expiration time to delete the object after
668 * @return true on success; false otherwise
670 bool remove(const std::string &key, time_t expiration)
672 return memcached_success(memcached_delete(memc,
679 * Delete an object from the server specified by the key given.
681 * @param[in] master_key specifies server to remove object from
682 * @param[in] key key of object to delete
683 * @return true on success; false otherwise
685 bool removeByKey(const std::string &master_key,
686 const std::string &key)
688 return memcached_success(memcached_delete_by_key(memc,
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 return memcached_success(memcached_delete_by_key(memc,
717 * Wipe the contents of memcached servers.
719 * @param[in] expiration time to wait until wiping contents of
721 * @return true on success; false otherwise
723 bool flush(time_t expiration= 0)
725 return memcached_success(memcached_flush(memc, expiration));
729 * Get the library version string.
730 * @return std::string containing a copy of the library version string.
732 const std::string libVersion() const
734 const char *ver= memcached_lib_version();
735 const std::string version(ver);
740 * Retrieve memcached statistics. Populate a std::map with the retrieved
741 * stats. Each server will map to another std::map of the key:value stats.
743 * @param[out] stats_map a std::map to be populated with the memcached
745 * @return true on success; false otherwise
747 bool getStats(std::map< std::string, std::map<std::string, std::string> >
750 memcached_return_t rc;
751 memcached_stat_st *stats= memcached_stat(memc, NULL, &rc);
753 if (rc != MEMCACHED_SUCCESS &&
754 rc != MEMCACHED_SOME_ERRORS)
759 uint32_t server_count= memcached_server_count(memc);
762 * For each memcached server, construct a std::map for its stats and add
763 * it to the std::map of overall stats.
765 for (uint32_t x= 0; x < server_count; x++)
767 memcached_server_instance_st instance=
768 memcached_server_instance_by_position(memc, x);
769 std::ostringstream strstm;
770 std::string server_name(memcached_server_name(instance));
771 server_name.append(":");
772 strstm << memcached_server_port(instance);
773 server_name.append(strstm.str());
775 std::map<std::string, std::string> server_stats;
779 list= memcached_stat_get_keys(memc, &stats[x], &rc);
780 for (ptr= list; *ptr; ptr++)
782 char *value= memcached_stat_get_value(memc, &stats[x], *ptr, &rc);
783 server_stats[*ptr]= value;
787 stats_map[server_name]= server_stats;
791 memcached_stat_free(memc, stats);