Merge in trunk. Updates to manual/update to latest libtest.
[m6w6/libmemcached] / libmemcached / memcached.hpp
1 /*
2 * Summary: C++ interface for memcached server
3 *
4 * Copy: See Copyright for the status of this software.
5 *
6 * Authors: Padraig O'Sullivan <osullivan.padraig@gmail.com>
7 * Patrick Galbraith <patg@patg.net>
8 */
9
10 /**
11 * @file memcached.hpp
12 * @brief Libmemcached C++ interface
13 */
14
15 #pragma once
16
17 #include <libmemcached/memcached.h>
18 #include <libmemcached/exception.hpp>
19
20 #include <string.h>
21
22 #include <sstream>
23 #include <string>
24 #include <vector>
25 #include <map>
26
27 namespace memcache
28 {
29
30 /**
31 * This is the core memcached library (if later, other objects
32 * are needed, they will be created from this class).
33 */
34 class Memcache
35 {
36 public:
37
38 Memcache()
39 {
40 memc= memcached("", 0);
41 }
42
43 Memcache(const std::string &config)
44 {
45 memc= memcached(config.c_str(), config.size());
46 }
47
48 Memcache(const std::string &hostname, in_port_t port)
49 {
50 memc= memcached("", 0);
51 if (memc)
52 memcached_server_add(memc, hostname.c_str(), port);
53 }
54
55 Memcache(memcached_st *clone)
56 {
57 memc= memcached_clone(NULL, clone);
58 }
59
60 Memcache(const Memcache &rhs)
61 {
62 memc= memcached_clone(NULL, rhs.getImpl());
63 }
64
65 Memcache &operator=(const Memcache &rhs)
66 {
67 if (this != &rhs)
68 {
69 memcached_free(memc);
70 memc= memcached_clone(NULL, rhs.getImpl());
71 }
72
73 return *this;
74 }
75
76 ~Memcache()
77 {
78 memcached_free(memc);
79 }
80
81 /**
82 * Get the internal memcached_st *
83 */
84 const memcached_st *getImpl() const
85 {
86 return memc;
87 }
88
89 /**
90 * Return an error string for the given return structure.
91 *
92 * @param[in] rc a memcached_return_t structure
93 * @return error string corresponding to given return code in the library.
94 */
95 const std::string getError(memcached_return_t rc) const
96 {
97 /* first parameter to strerror is unused */
98 return memcached_strerror(NULL, rc);
99 }
100
101
102 bool setBehavior(memcached_behavior_t flag, uint64_t data)
103 {
104 return (memcached_success(memcached_behavior_set(memc, flag, data)));
105 }
106
107 uint64_t getBehavior(memcached_behavior_t flag)
108 {
109 return memcached_behavior_get(memc, flag);
110 }
111
112 /**
113 * Configure the memcache object
114 *
115 * @param[in] in_config configuration
116 * @return true on success; false otherwise
117 */
118 bool configure(const std::string &configuration)
119 {
120 memcached_st *new_memc= memcached(configuration.c_str(), configuration.size());
121
122 if (new_memc)
123 {
124 memcached_free(memc);
125 memc= new_memc;
126
127 return true;
128 }
129
130 return false;
131 }
132
133 /**
134 * Add a server to the list of memcached servers to use.
135 *
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
139 */
140 bool addServer(const std::string &server_name, in_port_t port)
141 {
142 return memcached_success(memcached_server_add(memc, server_name.c_str(), port));
143 }
144
145 /**
146 * Remove a server from the list of memcached servers to use.
147 *
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
151 */
152 bool removeServer(const std::string &server_name, in_port_t port)
153 {
154 std::string tmp_str;
155 std::ostringstream strstm;
156 tmp_str.append(",");
157 tmp_str.append(server_name);
158 tmp_str.append(":");
159 strstm << port;
160 tmp_str.append(strstm.str());
161
162 //memcached_return_t rc= memcached_server_remove(server);
163
164 return false;
165 }
166
167 /**
168 * Fetches an individual value from the server. mget() must always
169 * be called before using this method.
170 *
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
174 */
175 memcached_return_t fetch(std::string &key,
176 std::vector<char> &ret_val,
177 uint32_t &flags,
178 uint64_t &cas_value)
179 {
180 memcached_return_t rc;
181
182 memcached_result_st *result;
183 if ((result= memcached_fetch_result(memc, NULL, &rc)))
184 {
185 // Key
186 key.assign(memcached_result_key_value(result), memcached_result_key_length(result));
187
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));
192
193 // Misc
194 flags= memcached_result_flags(result);
195 cas_value= memcached_result_cas(result);
196 }
197 memcached_result_free(result);
198
199 return rc;
200 }
201
202 memcached_return_t fetch(std::string &key,
203 std::vector<char> &ret_val)
204 {
205 uint32_t flags= 0;
206 uint64_t cas_value= 0;
207
208 return fetch(key, ret_val, flags, cas_value);
209 }
210
211 /**
212 * Fetches an individual value from the server.
213 *
214 * @param[in] key key of object whose value to get
215 * @param[out] ret_val object that is retrieved is stored in
216 * this vector
217 * @return true on success; false otherwise
218 */
219 bool get(const std::string &key, std::vector<char> &ret_val)
220 {
221 uint32_t flags= 0;
222 memcached_return_t rc;
223 size_t value_length= 0;
224
225 char *value= memcached_get(memc, key.c_str(), key.length(),
226 &value_length, &flags, &rc);
227 if (value != NULL && ret_val.empty())
228 {
229 ret_val.reserve(value_length);
230 ret_val.assign(value, value + value_length);
231 free(value);
232 return true;
233 }
234
235 return false;
236 }
237
238 /**
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
242 * used for storage.
243 *
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
247 * this vector
248 * @return true on success; false otherwise
249 */
250 bool getByKey(const std::string &master_key,
251 const std::string &key,
252 std::vector<char> &ret_val)
253 {
254 uint32_t flags= 0;
255 memcached_return_t rc;
256 size_t value_length= 0;
257
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);
262 if (value)
263 {
264 ret_val.reserve(value_length);
265 ret_val.assign(value, value + value_length);
266 free(value);
267 return true;
268 }
269 return false;
270 }
271
272 /**
273 * Selects multiple keys at once. This method always
274 * works asynchronously.
275 *
276 * @param[in] keys vector of keys to select
277 * @return true if all keys are found
278 */
279 bool mget(std::vector<std::string> &keys)
280 {
281 std::vector<const char *> real_keys;
282 std::vector<size_t> key_len;
283 /*
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 *.
288 */
289 real_keys.reserve(keys.size());
290 key_len.reserve(keys.size());
291
292 std::vector<std::string>::iterator it= keys.begin();
293
294 while (it != keys.end())
295 {
296 real_keys.push_back(const_cast<char *>((*it).c_str()));
297 key_len.push_back((*it).length());
298 ++it;
299 }
300
301 /*
302 * If the std::vector of keys is empty then we cannot
303 * call memcached_mget as we will get undefined behavior.
304 */
305 if (not real_keys.empty())
306 {
307 return memcached_success(memcached_mget(memc, &real_keys[0], &key_len[0], real_keys.size()));
308 }
309
310 return false;
311 }
312
313 /**
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.
317 *
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
323 */
324 bool set(const std::string &key,
325 const std::vector<char> &value,
326 time_t expiration,
327 uint32_t flags)
328 {
329 memcached_return_t rc= memcached_set(memc,
330 key.c_str(), key.length(),
331 &value[0], value.size(),
332 expiration, flags);
333 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
334 }
335
336 /**
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.
339 *
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
346 */
347 bool setByKey(const std::string &master_key,
348 const std::string &key,
349 const std::vector<char> &value,
350 time_t expiration,
351 uint32_t flags)
352 {
353 return memcached_success(memcached_set_by_key(memc, master_key.c_str(),
354 master_key.length(),
355 key.c_str(), key.length(),
356 &value[0], value.size(),
357 expiration,
358 flags));
359 }
360
361 /**
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.
364 *
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
370 */
371 bool setAll(std::vector<std::string> &keys,
372 std::vector< std::vector<char> *> &values,
373 time_t expiration,
374 uint32_t flags)
375 {
376 bool retval= true;
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())
380 {
381 retval= set((*key_it), *(*val_it), expiration, flags);
382 if (retval == false)
383 {
384 return retval;
385 }
386 ++key_it;
387 ++val_it;
388 }
389 return retval;
390 }
391
392 /**
393 * Writes a list of objects to the server. Objects are specified by
394 * a map of keys to values.
395 *
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
400 */
401 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
402 time_t expiration,
403 uint32_t flags)
404 {
405 bool retval= true;
406 std::map<const std::string, std::vector<char> >::iterator it= key_value_map.begin();
407
408 while (it != key_value_map.end())
409 {
410 retval= set(it->first, it->second, expiration, flags);
411 if (retval == false)
412 {
413 // We should tell the user what the key that failed was
414 return false;
415 }
416 ++it;
417 }
418 return true;
419 }
420
421 /**
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
424 * parameter.
425 *
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
430 */
431 bool increment(const std::string &key, uint32_t offset, uint64_t *value)
432 {
433 return memcached_success(memcached_increment(memc, key.c_str(), key.length(), offset, value));
434 }
435
436 /**
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
439 * parameter.
440 *
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
445 */
446 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
447 {
448 return memcached_success(memcached_decrement(memc, key.c_str(),
449 key.length(),
450 offset, value));
451 }
452
453
454 /**
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.
457 *
458 * @param[in] key key of object to add
459 * @param[in] value of object to add
460 * @return true on success; false otherwise
461 */
462 bool add(const std::string &key, const std::vector<char> &value)
463 {
464 return memcached_success(memcached_add(memc, key.c_str(), key.length(),
465 &value[0], value.size(), 0, 0));
466 }
467
468 /**
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.
472 *
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
477 */
478 bool addByKey(const std::string &master_key,
479 const std::string &key,
480 const std::vector<char> &value)
481 {
482 return memcached_success(memcached_add_by_key(memc,
483 master_key.c_str(),
484 master_key.length(),
485 key.c_str(),
486 key.length(),
487 &value[0],
488 value.size(),
489 0, 0));
490 }
491
492 /**
493 * Replaces an object on the server. This method only succeeds
494 * if the object is already present on the server.
495 *
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
499 */
500 bool replace(const std::string &key, const std::vector<char> &value)
501 {
502 return memcached_success(memcached_replace(memc, key.c_str(), key.length(),
503 &value[0], value.size(),
504 0, 0));
505 }
506
507 /**
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.
511 *
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
516 */
517 bool replaceByKey(const std::string &master_key,
518 const std::string &key,
519 const std::vector<char> &value)
520 {
521 return memcached_success(memcached_replace_by_key(memc,
522 master_key.c_str(),
523 master_key.length(),
524 key.c_str(),
525 key.length(),
526 &value[0],
527 value.size(),
528 0, 0));
529 }
530
531 /**
532 * Places a segment of data before the last piece of data stored.
533 *
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
537 */
538 bool prepend(const std::string &key, const std::vector<char> &value)
539 {
540 return memcached_success(memcached_prepend(memc, key.c_str(), key.length(),
541 &value[0], value.size(), 0, 0));
542 }
543
544 /**
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.
548 *
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
553 */
554 bool prependByKey(const std::string &master_key,
555 const std::string &key,
556 const std::vector<char> &value)
557 {
558 return memcached_success(memcached_prepend_by_key(memc,
559 master_key.c_str(),
560 master_key.length(),
561 key.c_str(),
562 key.length(),
563 &value[0],
564 value.size(),
565 0,
566 0));
567 }
568
569 /**
570 * Places a segment of data at the end of the last piece of data stored.
571 *
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
575 */
576 bool append(const std::string &key, const std::vector<char> &value)
577 {
578 return memcached_success(memcached_append(memc,
579 key.c_str(),
580 key.length(),
581 &value[0],
582 value.size(),
583 0, 0));
584 }
585
586 /**
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.
590 *
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
595 */
596 bool appendByKey(const std::string &master_key,
597 const std::string &key,
598 const std::vector<char> &value)
599 {
600 return memcached_success(memcached_append_by_key(memc,
601 master_key.c_str(),
602 master_key.length(),
603 key.c_str(),
604 key.length(),
605 &value[0],
606 value.size(),
607 0, 0));
608 }
609
610 /**
611 * Overwrite data in the server as long as the cas_arg value
612 * is still the same in the server.
613 *
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
617 */
618 bool cas(const std::string &key,
619 const std::vector<char> &value,
620 uint64_t cas_arg)
621 {
622 return memcached_success(memcached_cas(memc, key.c_str(), key.length(),
623 &value[0], value.size(),
624 0, 0, cas_arg));
625 }
626
627 /**
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.
631 *
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
636 */
637 bool casByKey(const std::string &master_key,
638 const std::string &key,
639 const std::vector<char> &value,
640 uint64_t cas_arg)
641 {
642 return memcached_success(memcached_cas_by_key(memc,
643 master_key.c_str(),
644 master_key.length(),
645 key.c_str(),
646 key.length(),
647 &value[0],
648 value.size(),
649 0, 0, cas_arg));
650 }
651
652 /**
653 * Delete an object from the server specified by the key given.
654 *
655 * @param[in] key key of object to delete
656 * @return true on success; false otherwise
657 */
658 bool remove(const std::string &key)
659 {
660 return memcached_success(memcached_delete(memc, key.c_str(), key.length(), 0));
661 }
662
663 /**
664 * Delete an object from the server specified by the key given.
665 *
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
669 */
670 bool remove(const std::string &key, time_t expiration)
671 {
672 return memcached_success(memcached_delete(memc,
673 key.c_str(),
674 key.length(),
675 expiration));
676 }
677
678 /**
679 * Delete an object from the server specified by the key given.
680 *
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
684 */
685 bool removeByKey(const std::string &master_key,
686 const std::string &key)
687 {
688 return memcached_success(memcached_delete_by_key(memc,
689 master_key.c_str(),
690 master_key.length(),
691 key.c_str(),
692 key.length(),
693 0));
694 }
695
696 /**
697 * Delete an object from the server specified by the key given.
698 *
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
703 */
704 bool removeByKey(const std::string &master_key,
705 const std::string &key,
706 time_t expiration)
707 {
708 return memcached_success(memcached_delete_by_key(memc,
709 master_key.c_str(),
710 master_key.length(),
711 key.c_str(),
712 key.length(),
713 expiration));
714 }
715
716 /**
717 * Wipe the contents of memcached servers.
718 *
719 * @param[in] expiration time to wait until wiping contents of
720 * memcached servers
721 * @return true on success; false otherwise
722 */
723 bool flush(time_t expiration= 0)
724 {
725 return memcached_success(memcached_flush(memc, expiration));
726 }
727
728 /**
729 * Get the library version string.
730 * @return std::string containing a copy of the library version string.
731 */
732 const std::string libVersion() const
733 {
734 const char *ver= memcached_lib_version();
735 const std::string version(ver);
736 return version;
737 }
738
739 /**
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.
742 *
743 * @param[out] stats_map a std::map to be populated with the memcached
744 * stats
745 * @return true on success; false otherwise
746 */
747 bool getStats(std::map< std::string, std::map<std::string, std::string> >
748 &stats_map)
749 {
750 memcached_return_t rc;
751 memcached_stat_st *stats= memcached_stat(memc, NULL, &rc);
752
753 if (rc != MEMCACHED_SUCCESS &&
754 rc != MEMCACHED_SOME_ERRORS)
755 {
756 return false;
757 }
758
759 uint32_t server_count= memcached_server_count(memc);
760
761 /*
762 * For each memcached server, construct a std::map for its stats and add
763 * it to the std::map of overall stats.
764 */
765 for (uint32_t x= 0; x < server_count; x++)
766 {
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());
774
775 std::map<std::string, std::string> server_stats;
776 char **list= NULL;
777 char **ptr= NULL;
778
779 list= memcached_stat_get_keys(memc, &stats[x], &rc);
780 for (ptr= list; *ptr; ptr++)
781 {
782 char *value= memcached_stat_get_value(memc, &stats[x], *ptr, &rc);
783 server_stats[*ptr]= value;
784 free(value);
785 }
786
787 stats_map[server_name]= server_stats;
788 free(list);
789 }
790
791 memcached_stat_free(memc, stats);
792 return true;
793 }
794
795 private:
796 memcached_st *memc;
797 };
798
799 }