2 +--------------------------------------------------------------------+
3 | libmemcached-awesome - C/C++ Client Library for memcached |
4 +--------------------------------------------------------------------+
5 | Redistribution and use in source and binary forms, with or without |
6 | modification, are permitted under the terms of the BSD license. |
7 | You should have received a copy of the license in a bundled file |
8 | named LICENSE; in case you did not receive a copy you can review |
9 | the terms online at: https://opensource.org/licenses/BSD-3-Clause |
10 +--------------------------------------------------------------------+
11 | Copyright (c) 2006-2014 Brian Aker https://datadifferential.com/ |
12 | Copyright (c) 2020-2021 Michael Wallner https://awesome.co/ |
13 +--------------------------------------------------------------------+
18 #include "libmemcached-1.0/memcached.h"
20 # 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).
37 Memcache() { memc_ = memcached(NULL, 0); }
39 Memcache(const std::string &config) { memc_ = memcached(config.c_str(), config.size()); }
41 Memcache(const std::string &hostname, in_port_t port) {
42 memc_ = memcached(NULL, 0);
44 memcached_server_add(memc_, hostname.c_str(), port);
48 Memcache(memcached_st *clone) { memc_ = memcached_clone(NULL, clone); }
50 Memcache(const Memcache &rhs) { memc_ = memcached_clone(NULL, rhs.getImpl()); }
52 Memcache &operator=(const Memcache &rhs) {
54 memcached_free(memc_);
55 memc_ = memcached_clone(NULL, rhs.getImpl());
61 ~Memcache() { memcached_free(memc_); }
64 * Get the internal memcached_st *
66 const memcached_st *getImpl() const { return memc_; }
69 * Return an error string for the given return structure.
71 * @param[in] rc a memcached_return_t structure
72 * @return error string corresponding to given return code in the library.
74 const std::string getError(memcached_return_t rc) const {
75 /* first parameter to strerror is unused */
76 return memcached_strerror(NULL, rc);
79 bool error(std::string &error_message) const {
80 if (memcached_failed(memcached_last_error(memc_))) {
81 error_message += memcached_last_error_message(memc_);
89 if (memcached_failed(memcached_last_error(memc_))) {
96 bool error(memcached_return_t &arg) const {
97 arg = memcached_last_error(memc_);
98 return memcached_failed(arg);
101 bool setBehavior(memcached_behavior_t flag, uint64_t data) {
102 return (memcached_success(memcached_behavior_set(memc_, flag, data)));
105 uint64_t getBehavior(memcached_behavior_t flag) { return memcached_behavior_get(memc_, flag); }
108 * Configure the memcache object
110 * @param[in] in_config configuration
111 * @return true on success; false otherwise
113 bool configure(const std::string &configuration) {
114 memcached_st *new_memc = memcached(configuration.c_str(), configuration.size());
117 memcached_free(memc_);
127 * Add a server to the list of memcached servers to use.
129 * @param[in] server_name name of the server to add
130 * @param[in] port port number of server to add
131 * @return true on success; false otherwise
133 bool addServer(const std::string &server_name, in_port_t port) {
134 return memcached_success(memcached_server_add(memc_, server_name.c_str(), port));
138 * Remove a server from the list of memcached servers to use.
140 * @param[in] server_name name of the server to remove
141 * @param[in] port port number of server to remove
142 * @return true on success; false otherwise
144 bool removeServer(const std::string &server_name, in_port_t port) {
146 std::ostringstream strstm;
148 tmp_str.append(server_name);
151 tmp_str.append(strstm.str());
153 // memcached_return_t rc= memcached_server_remove(server);
159 * Fetches an individual value from the server. mget() must always
160 * be called before using this method.
162 * @param[in] key key of object to fetch
163 * @param[out] ret_val store returned object in this vector
164 * @return a memcached return structure
166 memcached_return_t fetch(std::string &key, std::vector<char> &ret_val, uint32_t &flags,
167 uint64_t &cas_value) {
168 memcached_return_t rc;
170 memcached_result_st *result;
171 if ((result = memcached_fetch_result(memc_, NULL, &rc))) {
173 key.assign(memcached_result_key_value(result), memcached_result_key_length(result));
175 // Actual value, null terminated
176 ret_val.reserve(memcached_result_length(result) + 1);
177 ret_val.assign(memcached_result_value(result),
178 memcached_result_value(result) + memcached_result_length(result) + 1);
179 ret_val.resize(memcached_result_length(result));
182 flags = memcached_result_flags(result);
183 cas_value = memcached_result_cas(result);
185 memcached_result_free(result);
190 memcached_return_t fetch(std::string &key, std::vector<char> &ret_val) {
192 uint64_t cas_value = 0;
194 return fetch(key, ret_val, flags, cas_value);
198 * Fetches an individual value from the server.
200 * @param[in] key key of object whose value to get
201 * @param[out] ret_val object that is retrieved is stored in
203 * @return true on success; false otherwise
205 bool get(const std::string &key, std::vector<char> &ret_val) {
207 memcached_return_t rc;
208 size_t value_length = 0;
210 char *value = memcached_get(memc_, key.c_str(), key.length(), &value_length, &flags, &rc);
211 if (value != NULL && ret_val.empty()) {
212 ret_val.reserve(value_length + 1); // Always provide null
213 ret_val.assign(value, value + value_length + 1);
214 ret_val.resize(value_length);
224 * Fetches an individual from a server which is specified by
225 * the master_key parameter that is used for determining which
226 * server an object was stored in if key partitioning was
229 * @param[in] master_key key that specifies server object is stored on
230 * @param[in] key key of object whose value to get
231 * @param[out] ret_val object that is retrieved is stored in
233 * @return true on success; false otherwise
235 bool getByKey(const std::string &master_key, const std::string &key, std::vector<char> &ret_val) {
237 memcached_return_t rc;
238 size_t value_length = 0;
240 char *value = memcached_get_by_key(memc_, master_key.c_str(), master_key.length(), key.c_str(),
241 key.length(), &value_length, &flags, &rc);
243 ret_val.reserve(value_length + 1); // Always provide null
244 ret_val.assign(value, value + value_length + 1);
245 ret_val.resize(value_length);
254 * Selects multiple keys at once. This method always
255 * works asynchronously.
257 * @param[in] keys vector of keys to select
258 * @return true if all keys are found
260 bool mget(const std::vector<std::string> &keys) {
261 std::vector<const char *> real_keys;
262 std::vector<size_t> key_len;
264 * Construct an array which will contain the length
265 * of each of the strings in the input vector. Also, to
266 * interface with the memcached C API, we need to convert
267 * the vector of std::string's to a vector of char *.
269 real_keys.reserve(keys.size());
270 key_len.reserve(keys.size());
272 std::vector<std::string>::const_iterator it = keys.begin();
274 while (it != keys.end()) {
275 real_keys.push_back(const_cast<char *>((*it).c_str()));
276 key_len.push_back((*it).length());
281 * If the std::vector of keys is empty then we cannot
282 * call memcached_mget as we will get undefined behavior.
284 if (not real_keys.empty()) {
285 return memcached_success(memcached_mget(memc_, &real_keys[0], &key_len[0], real_keys.size()));
292 * Writes an object to the server. If the object already exists, it will
293 * overwrite the existing object. This method always returns true
294 * when using non-blocking mode unless a network error occurs.
296 * @param[in] key key of object to write to server
297 * @param[in] value value of object to write to server
298 * @param[in] expiration time to keep the object stored in the server for
299 * @param[in] flags flags to store with the object
300 * @return true on succcess; false otherwise
302 bool set(const std::string &key, const std::vector<char> &value, time_t expiration,
304 memcached_return_t rc = memcached_set(memc_, key.c_str(), key.length(), value.data(),
305 value.size(), expiration, flags);
306 return memcached_success(rc);
309 bool set(const std::string &key, const char *value, const size_t value_length, time_t expiration,
311 memcached_return_t rc =
312 memcached_set(memc_, key.c_str(), key.length(), value, value_length, expiration, flags);
313 return memcached_success(rc);
317 * Writes an object to a server specified by the master_key parameter.
318 * If the object already exists, it will overwrite the existing object.
320 * @param[in] master_key key that specifies server to write to
321 * @param[in] key key of object to write to server
322 * @param[in] value value of object to write to server
323 * @param[in] expiration time to keep the object stored in the server for
324 * @param[in] flags flags to store with the object
325 * @return true on succcess; false otherwise
327 bool setByKey(const std::string &master_key, const std::string &key,
328 const std::vector<char> &value, time_t expiration, uint32_t flags) {
329 return memcached_success(memcached_set_by_key(memc_, master_key.c_str(), master_key.length(),
330 key.c_str(), key.length(), &value[0],
331 value.size(), expiration, flags));
335 * Writes a list of objects to the server. Objects are specified by
336 * 2 vectors - 1 vector of keys and 1 vector of values.
338 * @param[in] keys vector of keys of objects to write to server
339 * @param[in] values vector of values of objects to write to server
340 * @param[in] expiration time to keep the objects stored in server for
341 * @param[in] flags flags to store with the objects
342 * @return true on success; false otherwise
344 bool setAll(const std::vector<std::string> &keys, const std::vector<std::vector<char> *> &values,
345 time_t expiration, uint32_t flags) {
347 std::vector<std::string>::const_iterator key_it = keys.begin();
348 std::vector<std::vector<char> *>::const_iterator val_it = values.begin();
349 while (key_it != keys.end()) {
350 retval = set((*key_it), *(*val_it), expiration, flags);
351 if (retval == false) {
361 * Writes a list of objects to the server. Objects are specified by
362 * a map of keys to values.
364 * @param[in] key_value_map map of keys and values to store in server
365 * @param[in] expiration time to keep the objects stored in server for
366 * @param[in] flags flags to store with the objects
367 * @return true on success; false otherwise
369 bool setAll(const std::map<const std::string, std::vector<char>> &key_value_map,
370 time_t expiration, uint32_t flags) {
371 std::map<const std::string, std::vector<char>>::const_iterator it = key_value_map.begin();
373 while (it != key_value_map.end()) {
374 if (!set(it->first, it->second, expiration, flags)) {
375 // We should tell the user what the key that failed was
385 * Increment the value of the object associated with the specified
386 * key by the offset given. The resulting value is saved in the value
389 * @param[in] key key of object in server whose value to increment
390 * @param[in] offset amount to increment object's value by
391 * @param[out] value store the result of the increment here
392 * @return true on success; false otherwise
394 bool increment(const std::string &key, uint32_t offset, uint64_t *value) {
395 return memcached_success(memcached_increment(memc_, key.c_str(), key.length(), offset, value));
399 * Decrement the value of the object associated with the specified
400 * key by the offset given. The resulting value is saved in the value
403 * @param[in] key key of object in server whose value to decrement
404 * @param[in] offset amount to increment object's value by
405 * @param[out] value store the result of the decrement here
406 * @return true on success; false otherwise
408 bool decrement(const std::string &key, uint32_t offset, uint64_t *value) {
409 return memcached_success(memcached_decrement(memc_, key.c_str(), key.length(), offset, value));
413 * Add an object with the specified key and value to the server. This
414 * function returns false if the object already exists on the server.
416 * @param[in] key key of object to add
417 * @param[in] value of object to add
418 * @return true on success; false otherwise
420 bool add(const std::string &key, const std::vector<char> &value) {
421 return memcached_success(
422 memcached_add(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
426 * Add an object with the specified key and value to the server. This
427 * function returns false if the object already exists on the server. The
428 * server to add the object to is specified by the master_key parameter.
430 * @param[in[ master_key key of server to add object to
431 * @param[in] key key of object to add
432 * @param[in] value of object to add
433 * @return true on success; false otherwise
435 bool addByKey(const std::string &master_key, const std::string &key,
436 const std::vector<char> &value) {
437 return memcached_success(memcached_add_by_key(memc_, master_key.c_str(), master_key.length(),
438 key.c_str(), key.length(), &value[0],
439 value.size(), 0, 0));
443 * Replaces an object on the server. This method only succeeds
444 * if the object is already present on the server.
446 * @param[in] key key of object to replace
447 * @param[in[ value value to replace object with
448 * @return true on success; false otherwise
450 bool replace(const std::string &key, const std::vector<char> &value) {
451 return memcached_success(
452 memcached_replace(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
456 * Replaces an object on the server. This method only succeeds
457 * if the object is already present on the server. The server
458 * to replace the object on is specified by the master_key param.
460 * @param[in] master_key key of server to replace object on
461 * @param[in] key key of object to replace
462 * @param[in[ value value to replace object with
463 * @return true on success; false otherwise
465 bool replaceByKey(const std::string &master_key, const std::string &key,
466 const std::vector<char> &value) {
467 return memcached_success(memcached_replace_by_key(memc_, master_key.c_str(),
468 master_key.length(), key.c_str(),
469 key.length(), &value[0], value.size(), 0, 0));
473 * Places a segment of data before the last piece of data stored.
475 * @param[in] key key of object whose value we will prepend data to
476 * @param[in] value data to prepend to object's value
477 * @return true on success; false otherwise
479 bool prepend(const std::string &key, const std::vector<char> &value) {
480 return memcached_success(
481 memcached_prepend(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
485 * Places a segment of data before the last piece of data stored. The
486 * server on which the object where we will be prepending data is stored
487 * on is specified by the master_key parameter.
489 * @param[in] master_key key of server where object is stored
490 * @param[in] key key of object whose value we will prepend data to
491 * @param[in] value data to prepend to object's value
492 * @return true on success; false otherwise
494 bool prependByKey(const std::string &master_key, const std::string &key,
495 const std::vector<char> &value) {
496 return memcached_success(memcached_prepend_by_key(memc_, master_key.c_str(),
497 master_key.length(), key.c_str(),
498 key.length(), &value[0], value.size(), 0, 0));
502 * Places a segment of data at the end of the last piece of data stored.
504 * @param[in] key key of object whose value we will append data to
505 * @param[in] value data to append to object's value
506 * @return true on success; false otherwise
508 bool append(const std::string &key, const std::vector<char> &value) {
509 return memcached_success(
510 memcached_append(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0));
514 * Places a segment of data at the end of the last piece of data stored. The
515 * server on which the object where we will be appending data is stored
516 * on is specified by the master_key parameter.
518 * @param[in] master_key key of server where object is stored
519 * @param[in] key key of object whose value we will append data to
520 * @param[in] value data to append to object's value
521 * @return true on success; false otherwise
523 bool appendByKey(const std::string &master_key, const std::string &key,
524 const std::vector<char> &value) {
525 return memcached_success(memcached_append_by_key(memc_, master_key.c_str(), master_key.length(),
526 key.c_str(), key.length(), &value[0],
527 value.size(), 0, 0));
531 * Overwrite data in the server as long as the cas_arg value
532 * is still the same in the server.
534 * @param[in] key key of object in server
535 * @param[in] value value to store for object in server
536 * @param[in] cas_arg "cas" value
538 bool cas(const std::string &key, const std::vector<char> &value, uint64_t cas_arg) {
539 return memcached_success(
540 memcached_cas(memc_, key.c_str(), key.length(), &value[0], value.size(), 0, 0, cas_arg));
544 * Overwrite data in the server as long as the cas_arg value
545 * is still the same in the server. The server to use is
546 * specified by the master_key parameter.
548 * @param[in] master_key specifies server to operate on
549 * @param[in] key key of object in server
550 * @param[in] value value to store for object in server
551 * @param[in] cas_arg "cas" value
553 bool casByKey(const std::string &master_key, const std::string &key,
554 const std::vector<char> &value, uint64_t cas_arg) {
555 return memcached_success(memcached_cas_by_key(memc_, master_key.c_str(), master_key.length(),
556 key.c_str(), key.length(), &value[0],
557 value.size(), 0, 0, cas_arg));
561 * Delete an object from the server specified by the key given.
563 * @param[in] key key of object to delete
564 * @return true on success; false otherwise
566 bool remove(const std::string &key) {
567 return memcached_success(memcached_delete(memc_, key.c_str(), key.length(), 0));
571 * Delete an object from the server specified by the key given.
573 * @param[in] key key of object to delete
574 * @param[in] expiration time to delete the object after
575 * @return true on success; false otherwise
577 bool remove(const std::string &key, time_t expiration) {
578 return memcached_success(memcached_delete(memc_, key.c_str(), key.length(), expiration));
582 * Delete an object from the server specified by the key given.
584 * @param[in] master_key specifies server to remove object from
585 * @param[in] key key of object to delete
586 * @return true on success; false otherwise
588 bool removeByKey(const std::string &master_key, const std::string &key) {
589 return memcached_success(memcached_delete_by_key(memc_, master_key.c_str(), master_key.length(),
590 key.c_str(), key.length(), 0));
594 * Delete an object from the server specified by the key given.
596 * @param[in] master_key specifies server to remove object from
597 * @param[in] key key of object to delete
598 * @param[in] expiration time to delete the object after
599 * @return true on success; false otherwise
601 bool removeByKey(const std::string &master_key, const std::string &key, time_t expiration) {
602 return memcached_success(memcached_delete_by_key(memc_, master_key.c_str(), master_key.length(),
603 key.c_str(), key.length(), expiration));
607 * Wipe the contents of memcached servers.
609 * @param[in] expiration time to wait until wiping contents of
611 * @return true on success; false otherwise
613 bool flush(time_t expiration = 0) {
614 return memcached_success(memcached_flush(memc_, expiration));
618 * Get the library version string.
619 * @return std::string containing a copy of the library version string.
621 const std::string libVersion() const {
622 const char *ver = memcached_lib_version();
623 const std::string version(ver);
628 * Retrieve memcached statistics. Populate a std::map with the retrieved
629 * stats. Each server will map to another std::map of the key:value stats.
631 * @param[out] stats_map a std::map to be populated with the memcached
633 * @return true on success; false otherwise
635 bool getStats(std::map<std::string, std::map<std::string, std::string>> &stats_map) {
636 memcached_return_t rc;
637 memcached_stat_st *stats = memcached_stat(memc_, NULL, &rc);
639 if (rc != MEMCACHED_SUCCESS && rc != MEMCACHED_SOME_ERRORS) {
643 uint32_t server_count = memcached_server_count(memc_);
646 * For each memcached server, construct a std::map for its stats and add
647 * it to the std::map of overall stats.
649 for (uint32_t x = 0; x < server_count; x++) {
650 const memcached_instance_st *instance = memcached_server_instance_by_position(memc_, x);
651 std::ostringstream strstm;
652 std::string server_name(memcached_server_name(instance));
653 server_name.append(":");
654 strstm << memcached_server_port(instance);
655 server_name.append(strstm.str());
657 std::map<std::string, std::string> server_stats;
658 char **list = memcached_stat_get_keys(memc_, &stats[x], &rc);
659 for (char **ptr = list; *ptr; ptr++) {
660 char *value = memcached_stat_get_value(memc_, &stats[x], *ptr, &rc);
661 server_stats[*ptr] = value;
665 stats_map[server_name] = server_stats;
669 memcached_stat_free(memc_, stats);
677 } // namespace memcache