Partial encapsulation of memcached_st->hosts
[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 #ifndef LIBMEMCACHEDPP_H
16 #define LIBMEMCACHEDPP_H
17
18 #include <libmemcached/memcached.h>
19 #include <libmemcached/exception.hpp>
20
21 #include <string.h>
22
23 #include <sstream>
24 #include <string>
25 #include <vector>
26 #include <map>
27
28 namespace memcache
29 {
30
31 /**
32 * This is the core memcached library (if later, other objects
33 * are needed, they will be created from this class).
34 */
35 class Memcache
36 {
37 public:
38
39 Memcache()
40 :
41 servers_list(),
42 memc(),
43 servers(NULL),
44 result()
45 {
46 memcached_create(&memc);
47 }
48
49 Memcache(const std::string &in_servers_list)
50 :
51 servers_list(in_servers_list),
52 memc(),
53 servers(NULL),
54 result()
55 {
56 memcached_create(&memc);
57 servers= memcached_servers_parse(servers_list.c_str());
58 memcached_server_push(&memc, servers);
59 }
60
61 Memcache(const std::string &hostname,
62 in_port_t port)
63 :
64 servers_list(),
65 memc(),
66 servers(NULL),
67 result()
68 {
69 memcached_create(&memc);
70 servers_list.append(hostname);
71 servers_list.append(":");
72 std::ostringstream strsmt;
73 strsmt << port;
74 servers_list.append(strsmt.str());
75 servers= memcached_servers_parse(servers_list.c_str());
76 memcached_server_push(&memc, servers);
77 }
78
79 Memcache(memcached_st *clone)
80 :
81 servers_list(),
82 memc(),
83 servers(NULL),
84 result()
85 {
86 memcached_clone(&memc, clone);
87 }
88
89 Memcache(const Memcache &rhs)
90 :
91 servers_list(rhs.servers_list),
92 memc(),
93 servers(NULL),
94 result()
95 {
96 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
97 servers= memcached_servers_parse(servers_list.c_str());
98 memcached_server_push(&memc, servers);
99 }
100
101 Memcache &operator=(const Memcache &rhs)
102 {
103 if (this != &rhs)
104 {
105 memcached_clone(&memc, const_cast<memcached_st *>(&rhs.getImpl()));
106 servers= memcached_servers_parse(servers_list.c_str());
107 memcached_server_push(&memc, servers);
108 }
109 return *this;
110 }
111
112 ~Memcache()
113 {
114 memcached_free(&memc);
115 memcached_server_list_free(servers);
116 }
117
118 /**
119 * Get the internal memcached_st *
120 */
121 memcached_st &getImpl()
122 {
123 return memc;
124 }
125
126 /**
127 * Get the internal memcached_st *
128 */
129 const memcached_st &getImpl() const
130 {
131 return memc;
132 }
133
134 /**
135 * Return an error string for the given return structure.
136 *
137 * @param[in] rc a memcached_return_t structure
138 * @return error string corresponding to given return code in the library.
139 */
140 const std::string getError(memcached_return_t rc) const
141 {
142 /* first parameter to strerror is unused */
143 return memcached_strerror(NULL, rc);
144 }
145
146
147 bool setBehavior(memcached_behavior_t flag, uint64_t data)
148 {
149 memcached_return_t rc;
150 rc= memcached_behavior_set(&memc, flag, data);
151 return (rc == MEMCACHED_SUCCESS);
152 }
153
154 uint64_t getBehavior(memcached_behavior_t flag) {
155 return memcached_behavior_get(&memc, flag);
156 }
157
158 /**
159 * Return the string which contains the list of memcached servers being
160 * used.
161 *
162 * @return a std::string containing the list of memcached servers
163 */
164 const std::string getServersList() const
165 {
166 return servers_list;
167 }
168
169 /**
170 * Set the list of memcached servers to use.
171 *
172 * @param[in] in_servers_list list of servers
173 * @return true on success; false otherwise
174 */
175 bool setServers(const std::string &in_servers_list)
176 {
177 servers_list.assign(in_servers_list);
178 servers= memcached_servers_parse(in_servers_list.c_str());
179 memcached_server_push(&memc, servers);
180 return (servers == NULL);
181 }
182
183 /**
184 * Add a server to the list of memcached servers to use.
185 *
186 * @param[in] server_name name of the server to add
187 * @param[in] port port number of server to add
188 * @return true on success; false otherwise
189 */
190 bool addServer(const std::string &server_name, in_port_t port)
191 {
192 memcached_return_t rc;
193 std::ostringstream strstm;
194 servers_list.append(",");
195 servers_list.append(server_name);
196 servers_list.append(":");
197 strstm << port;
198 servers_list.append(strstm.str());
199 servers= memcached_server_list_append(servers,
200 server_name.c_str(),
201 port,
202 &rc);
203 memcached_server_push(&memc, servers);
204 return (rc == MEMCACHED_SUCCESS);
205 }
206
207 /**
208 * Remove a server from the list of memcached servers to use.
209 *
210 * @param[in] server_name name of the server to remove
211 * @param[in] port port number of server to remove
212 * @return true on success; false otherwise
213 */
214 bool removeServer(const std::string &server_name, in_port_t port)
215 {
216 std::string tmp_str;
217 std::ostringstream strstm;
218 tmp_str.append(",");
219 tmp_str.append(server_name);
220 tmp_str.append(":");
221 strstm << port;
222 tmp_str.append(strstm.str());
223 memcached_server_st *server= memcached_servers_parse(tmp_str.c_str());
224 memcached_return_t rc= memcached_server_remove(server);
225 return (rc == MEMCACHED_SUCCESS);
226 }
227
228 /**
229 * Fetches an individual value from the server. mget() must always
230 * be called before using this method.
231 *
232 * @param[in] key key of object to fetch
233 * @param[out] ret_val store returned object in this vector
234 * @return a memcached return structure
235 */
236 memcached_return_t fetch(std::string &key,
237 std::vector<char> &ret_val)
238 {
239 char ret_key[MEMCACHED_MAX_KEY];
240 size_t value_length= 0;
241 size_t key_length= 0;
242 memcached_return_t rc;
243 uint32_t flags= 0;
244 char *value= memcached_fetch(&memc, ret_key, &key_length,
245 &value_length, &flags, &rc);
246 if (value && ret_val.empty())
247 {
248 ret_val.reserve(value_length);
249 ret_val.assign(value, value + value_length);
250 key.assign(ret_key);
251 free(value);
252 }
253 else if (value)
254 {
255 free(value);
256 }
257
258 return rc;
259 }
260
261 /**
262 * Fetches an individual value from the server.
263 *
264 * @param[in] key key of object whose value to get
265 * @param[out] ret_val object that is retrieved is stored in
266 * this vector
267 * @return true on success; false otherwise
268 */
269 bool get(const std::string &key,
270 std::vector<char> &ret_val) throw (Error)
271 {
272 uint32_t flags= 0;
273 memcached_return_t rc;
274 size_t value_length= 0;
275
276 if (key.empty())
277 {
278 throw(Error("the key supplied is empty!", false));
279 }
280 char *value= memcached_get(&memc, key.c_str(), key.length(),
281 &value_length, &flags, &rc);
282 if (value != NULL && ret_val.empty())
283 {
284 ret_val.reserve(value_length);
285 ret_val.assign(value, value + value_length);
286 free(value);
287 return true;
288 }
289 return false;
290 }
291
292 /**
293 * Fetches an individual from a server which is specified by
294 * the master_key parameter that is used for determining which
295 * server an object was stored in if key partitioning was
296 * used for storage.
297 *
298 * @param[in] master_key key that specifies server object is stored on
299 * @param[in] key key of object whose value to get
300 * @param[out] ret_val object that is retrieved is stored in
301 * this vector
302 * @return true on success; false otherwise
303 */
304 bool getByKey(const std::string &master_key,
305 const std::string &key,
306 std::vector<char> &ret_val) throw(Error)
307 {
308 uint32_t flags= 0;
309 memcached_return_t rc;
310 size_t value_length= 0;
311
312 if (master_key.empty() || key.empty())
313 {
314 throw(Error("the master key or key supplied is empty!", false));
315 }
316 char *value= memcached_get_by_key(&memc,
317 master_key.c_str(), master_key.length(),
318 key.c_str(), key.length(),
319 &value_length, &flags, &rc);
320 if (value)
321 {
322 ret_val.reserve(value_length);
323 ret_val.assign(value, value + value_length);
324 free(value);
325 return true;
326 }
327 return false;
328 }
329
330 /**
331 * Selects multiple keys at once. This method always
332 * works asynchronously.
333 *
334 * @param[in] keys vector of keys to select
335 * @return true if all keys are found
336 */
337 bool mget(std::vector<std::string> &keys)
338 {
339 std::vector<const char *> real_keys;
340 std::vector<size_t> key_len;
341 /*
342 * Construct an array which will contain the length
343 * of each of the strings in the input vector. Also, to
344 * interface with the memcached C API, we need to convert
345 * the vector of std::string's to a vector of char *.
346 */
347 real_keys.reserve(keys.size());
348 key_len.reserve(keys.size());
349
350 std::vector<std::string>::iterator it= keys.begin();
351
352 while (it != keys.end())
353 {
354 real_keys.push_back(const_cast<char *>((*it).c_str()));
355 key_len.push_back((*it).length());
356 ++it;
357 }
358
359 /*
360 * If the std::vector of keys is empty then we cannot
361 * call memcached_mget as we will get undefined behavior.
362 */
363 if (! real_keys.empty())
364 {
365 memcached_return_t rc= memcached_mget(&memc, &real_keys[0], &key_len[0],
366 real_keys.size());
367 return (rc == MEMCACHED_SUCCESS);
368 }
369
370 return false;
371 }
372
373 /**
374 * Writes an object to the server. If the object already exists, it will
375 * overwrite the existing object. This method always returns true
376 * when using non-blocking mode unless a network error occurs.
377 *
378 * @param[in] key key of object to write to server
379 * @param[in] value value of object to write to server
380 * @param[in] expiration time to keep the object stored in the server for
381 * @param[in] flags flags to store with the object
382 * @return true on succcess; false otherwise
383 */
384 bool set(const std::string &key,
385 const std::vector<char> &value,
386 time_t expiration,
387 uint32_t flags) throw(Error)
388 {
389 if (key.empty() || value.empty())
390 {
391 throw(Error("the key or value supplied is empty!", false));
392 }
393 memcached_return_t rc= memcached_set(&memc,
394 key.c_str(), key.length(),
395 &value[0], value.size(),
396 expiration, flags);
397 return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED);
398 }
399
400 /**
401 * Writes an object to a server specified by the master_key parameter.
402 * If the object already exists, it will overwrite the existing object.
403 *
404 * @param[in] master_key key that specifies server to write to
405 * @param[in] key key of object to write to server
406 * @param[in] value value of object to write to server
407 * @param[in] expiration time to keep the object stored in the server for
408 * @param[in] flags flags to store with the object
409 * @return true on succcess; false otherwise
410 */
411 bool setByKey(const std::string &master_key,
412 const std::string &key,
413 const std::vector<char> &value,
414 time_t expiration,
415 uint32_t flags) throw(Error)
416 {
417 if (master_key.empty() ||
418 key.empty() ||
419 value.empty())
420 {
421 throw(Error("the key or value supplied is empty!", false));
422 }
423 memcached_return_t rc= memcached_set_by_key(&memc, master_key.c_str(),
424 master_key.length(),
425 key.c_str(), key.length(),
426 &value[0], value.size(),
427 expiration,
428 flags);
429 return (rc == MEMCACHED_SUCCESS);
430 }
431
432 /**
433 * Writes a list of objects to the server. Objects are specified by
434 * 2 vectors - 1 vector of keys and 1 vector of values.
435 *
436 * @param[in] keys vector of keys of objects to write to server
437 * @param[in] values vector of values of objects to write to server
438 * @param[in] expiration time to keep the objects stored in server for
439 * @param[in] flags flags to store with the objects
440 * @return true on success; false otherwise
441 */
442 bool setAll(std::vector<std::string> &keys,
443 std::vector< std::vector<char> *> &values,
444 time_t expiration,
445 uint32_t flags) throw(Error)
446 {
447 if (keys.size() != values.size())
448 {
449 throw(Error("The number of keys and values do not match!", false));
450 }
451 bool retval= true;
452 std::vector<std::string>::iterator key_it= keys.begin();
453 std::vector< std::vector<char> *>::iterator val_it= values.begin();
454 while (key_it != keys.end())
455 {
456 retval= set((*key_it), *(*val_it), expiration, flags);
457 if (retval == false)
458 {
459 return retval;
460 }
461 ++key_it;
462 ++val_it;
463 }
464 return retval;
465 }
466
467 /**
468 * Writes a list of objects to the server. Objects are specified by
469 * a map of keys to values.
470 *
471 * @param[in] key_value_map map of keys and values to store in server
472 * @param[in] expiration time to keep the objects stored in server for
473 * @param[in] flags flags to store with the objects
474 * @return true on success; false otherwise
475 */
476 bool setAll(std::map<const std::string, std::vector<char> > &key_value_map,
477 time_t expiration,
478 uint32_t flags) throw(Error)
479 {
480 if (key_value_map.empty())
481 {
482 throw(Error("The key/values are not properly set!", false));
483 }
484 bool retval= true;
485 std::map<const std::string, std::vector<char> >::iterator it=
486 key_value_map.begin();
487 while (it != key_value_map.end())
488 {
489 retval= set(it->first, it->second, expiration, flags);
490 if (retval == false)
491 {
492 std::string err_buff("There was an error setting the key ");
493 err_buff.append(it->first);
494 throw(Error(err_buff, false));
495 }
496 ++it;
497 }
498 return true;
499 }
500
501 /**
502 * Increment the value of the object associated with the specified
503 * key by the offset given. The resulting value is saved in the value
504 * parameter.
505 *
506 * @param[in] key key of object in server whose value to increment
507 * @param[in] offset amount to increment object's value by
508 * @param[out] value store the result of the increment here
509 * @return true on success; false otherwise
510 */
511 bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error)
512 {
513 if (key.empty())
514 {
515 throw(Error("the key supplied is empty!", false));
516 }
517 memcached_return_t rc= memcached_increment(&memc, key.c_str(), key.length(),
518 offset, value);
519 return (rc == MEMCACHED_SUCCESS);
520 }
521
522 /**
523 * Decrement the value of the object associated with the specified
524 * key by the offset given. The resulting value is saved in the value
525 * parameter.
526 *
527 * @param[in] key key of object in server whose value to decrement
528 * @param[in] offset amount to increment object's value by
529 * @param[out] value store the result of the decrement here
530 * @return true on success; false otherwise
531 */
532 bool decrement(const std::string &key, uint32_t offset, uint64_t *value)
533 throw(Error)
534 {
535 if (key.empty())
536 {
537 throw(Error("the key supplied is empty!", false));
538 }
539 memcached_return_t rc= memcached_decrement(&memc, key.c_str(),
540 key.length(),
541 offset, value);
542 return (rc == MEMCACHED_SUCCESS);
543 }
544
545
546 /**
547 * Add an object with the specified key and value to the server. This
548 * function returns false if the object already exists on the server.
549 *
550 * @param[in] key key of object to add
551 * @param[in] value of object to add
552 * @return true on success; false otherwise
553 */
554 bool add(const std::string &key, const std::vector<char> &value)
555 throw(Error)
556 {
557 if (key.empty() || value.empty())
558 {
559 throw(Error("the key or value supplied is empty!", false));
560 }
561 memcached_return_t rc= memcached_add(&memc, key.c_str(), key.length(),
562 &value[0], value.size(), 0, 0);
563 return (rc == MEMCACHED_SUCCESS);
564 }
565
566 /**
567 * Add an object with the specified key and value to the server. This
568 * function returns false if the object already exists on the server. The
569 * server to add the object to is specified by the master_key parameter.
570 *
571 * @param[in[ master_key key of server to add object to
572 * @param[in] key key of object to add
573 * @param[in] value of object to add
574 * @return true on success; false otherwise
575 */
576 bool addByKey(const std::string &master_key,
577 const std::string &key,
578 const std::vector<char> &value) throw(Error)
579 {
580 if (master_key.empty() ||
581 key.empty() ||
582 value.empty())
583 {
584 throw(Error("the master key or key supplied is empty!", false));
585 }
586 memcached_return_t rc= memcached_add_by_key(&memc,
587 master_key.c_str(),
588 master_key.length(),
589 key.c_str(),
590 key.length(),
591 &value[0],
592 value.size(),
593 0, 0);
594 return (rc == MEMCACHED_SUCCESS);
595 }
596
597 /**
598 * Replaces an object on the server. This method only succeeds
599 * if the object is already present on the server.
600 *
601 * @param[in] key key of object to replace
602 * @param[in[ value value to replace object with
603 * @return true on success; false otherwise
604 */
605 bool replace(const std::string &key, const std::vector<char> &value) throw(Error)
606 {
607 if (key.empty() ||
608 value.empty())
609 {
610 throw(Error("the key or value supplied is empty!", false));
611 }
612 memcached_return_t rc= memcached_replace(&memc, key.c_str(), key.length(),
613 &value[0], value.size(),
614 0, 0);
615 return (rc == MEMCACHED_SUCCESS);
616 }
617
618 /**
619 * Replaces an object on the server. This method only succeeds
620 * if the object is already present on the server. The server
621 * to replace the object on is specified by the master_key param.
622 *
623 * @param[in] master_key key of server to replace object on
624 * @param[in] key key of object to replace
625 * @param[in[ value value to replace object with
626 * @return true on success; false otherwise
627 */
628 bool replaceByKey(const std::string &master_key,
629 const std::string &key,
630 const std::vector<char> &value)
631 {
632 if (master_key.empty() ||
633 key.empty() ||
634 value.empty())
635 {
636 throw(Error("the master key or key supplied is empty!", false));
637 }
638 memcached_return_t rc= memcached_replace_by_key(&memc,
639 master_key.c_str(),
640 master_key.length(),
641 key.c_str(),
642 key.length(),
643 &value[0],
644 value.size(),
645 0, 0);
646 return (rc == MEMCACHED_SUCCESS);
647 }
648
649 /**
650 * Places a segment of data before the last piece of data stored.
651 *
652 * @param[in] key key of object whose value we will prepend data to
653 * @param[in] value data to prepend to object's value
654 * @return true on success; false otherwise
655 */
656 bool prepend(const std::string &key, const std::vector<char> &value)
657 throw(Error)
658 {
659 if (key.empty() || value.empty())
660 {
661 throw(Error("the key or value supplied is empty!", false));
662 }
663 memcached_return_t rc= memcached_prepend(&memc, key.c_str(), key.length(),
664 &value[0], value.size(), 0, 0);
665 return (rc == MEMCACHED_SUCCESS);
666 }
667
668 /**
669 * Places a segment of data before the last piece of data stored. The
670 * server on which the object where we will be prepending data is stored
671 * on is specified by the master_key parameter.
672 *
673 * @param[in] master_key key of server where object is stored
674 * @param[in] key key of object whose value we will prepend data to
675 * @param[in] value data to prepend to object's value
676 * @return true on success; false otherwise
677 */
678 bool prependByKey(const std::string &master_key,
679 const std::string &key,
680 const std::vector<char> &value)
681 throw(Error)
682 {
683 if (master_key.empty() ||
684 key.empty() ||
685 value.empty())
686 {
687 throw(Error("the master key or key supplied is empty!", false));
688 }
689 memcached_return_t rc= memcached_prepend_by_key(&memc,
690 master_key.c_str(),
691 master_key.length(),
692 key.c_str(),
693 key.length(),
694 &value[0],
695 value.size(),
696 0,
697 0);
698 return (rc == MEMCACHED_SUCCESS);
699 }
700
701 /**
702 * Places a segment of data at the end of the last piece of data stored.
703 *
704 * @param[in] key key of object whose value we will append data to
705 * @param[in] value data to append to object's value
706 * @return true on success; false otherwise
707 */
708 bool append(const std::string &key, const std::vector<char> &value)
709 throw(Error)
710 {
711 if (key.empty() || value.empty())
712 {
713 throw(Error("the key or value supplied is empty!", false));
714 }
715 memcached_return_t rc= memcached_append(&memc,
716 key.c_str(),
717 key.length(),
718 &value[0],
719 value.size(),
720 0, 0);
721 return (rc == MEMCACHED_SUCCESS);
722 }
723
724 /**
725 * Places a segment of data at the end of the last piece of data stored. The
726 * server on which the object where we will be appending data is stored
727 * on is specified by the master_key parameter.
728 *
729 * @param[in] master_key key of server where object is stored
730 * @param[in] key key of object whose value we will append data to
731 * @param[in] value data to append to object's value
732 * @return true on success; false otherwise
733 */
734 bool appendByKey(const std::string &master_key,
735 const std::string &key,
736 const std::vector<char> &value)
737 throw(Error)
738 {
739 if (master_key.empty() ||
740 key.empty() ||
741 value.empty())
742 {
743 throw(Error("the master key or key supplied is empty!", false));
744 }
745 memcached_return_t rc= memcached_append_by_key(&memc,
746 master_key.c_str(),
747 master_key.length(),
748 key.c_str(),
749 key.length(),
750 &value[0],
751 value.size(),
752 0, 0);
753 return (rc == MEMCACHED_SUCCESS);
754 }
755
756 /**
757 * Overwrite data in the server as long as the cas_arg value
758 * is still the same in the server.
759 *
760 * @param[in] key key of object in server
761 * @param[in] value value to store for object in server
762 * @param[in] cas_arg "cas" value
763 */
764 bool cas(const std::string &key,
765 const std::vector<char> &value,
766 uint64_t cas_arg) throw(Error)
767 {
768 if (key.empty() || value.empty())
769 {
770 throw(Error("the key or value supplied is empty!", false));
771 }
772 memcached_return_t rc= memcached_cas(&memc, key.c_str(), key.length(),
773 &value[0], value.size(),
774 0, 0, cas_arg);
775 return (rc == MEMCACHED_SUCCESS);
776 }
777
778 /**
779 * Overwrite data in the server as long as the cas_arg value
780 * is still the same in the server. The server to use is
781 * specified by the master_key parameter.
782 *
783 * @param[in] master_key specifies server to operate on
784 * @param[in] key key of object in server
785 * @param[in] value value to store for object in server
786 * @param[in] cas_arg "cas" value
787 */
788 bool casByKey(const std::string &master_key,
789 const std::string &key,
790 const std::vector<char> &value,
791 uint64_t cas_arg) throw(Error)
792 {
793 if (master_key.empty() ||
794 key.empty() ||
795 value.empty())
796 {
797 throw(Error("the master key, key or value supplied is empty!", false));
798 }
799 memcached_return_t rc= memcached_cas_by_key(&memc,
800 master_key.c_str(),
801 master_key.length(),
802 key.c_str(),
803 key.length(),
804 &value[0],
805 value.size(),
806 0, 0, cas_arg);
807 return (rc == MEMCACHED_SUCCESS);
808 }
809
810 /**
811 * Delete an object from the server specified by the key given.
812 *
813 * @param[in] key key of object to delete
814 * @return true on success; false otherwise
815 */
816 bool remove(const std::string &key) throw(Error)
817 {
818 if (key.empty())
819 {
820 throw(Error("the key supplied is empty!", false));
821 }
822 memcached_return_t rc= memcached_delete(&memc, key.c_str(), key.length(), 0);
823 return (rc == MEMCACHED_SUCCESS);
824 }
825
826 /**
827 * Delete an object from the server specified by the key given.
828 *
829 * @param[in] key key of object to delete
830 * @param[in] expiration time to delete the object after
831 * @return true on success; false otherwise
832 */
833 bool remove(const std::string &key,
834 time_t expiration) throw(Error)
835 {
836 if (key.empty())
837 {
838 throw(Error("the key supplied is empty!", false));
839 }
840 memcached_return_t rc= memcached_delete(&memc,
841 key.c_str(),
842 key.length(),
843 expiration);
844 return (rc == MEMCACHED_SUCCESS);
845 }
846
847 /**
848 * Delete an object from the server specified by the key given.
849 *
850 * @param[in] master_key specifies server to remove object from
851 * @param[in] key key of object to delete
852 * @return true on success; false otherwise
853 */
854 bool removeByKey(const std::string &master_key,
855 const std::string &key) throw(Error)
856 {
857 if (master_key.empty() || key.empty())
858 {
859 throw(Error("the master key or key supplied is empty!", false));
860 }
861 memcached_return_t rc= memcached_delete_by_key(&memc,
862 master_key.c_str(),
863 master_key.length(),
864 key.c_str(),
865 key.length(),
866 0);
867 return (rc == MEMCACHED_SUCCESS);
868 }
869
870 /**
871 * Delete an object from the server specified by the key given.
872 *
873 * @param[in] master_key specifies server to remove object from
874 * @param[in] key key of object to delete
875 * @param[in] expiration time to delete the object after
876 * @return true on success; false otherwise
877 */
878 bool removeByKey(const std::string &master_key,
879 const std::string &key,
880 time_t expiration) throw(Error)
881 {
882 if (master_key.empty() || key.empty())
883 {
884 throw(Error("the master key or key supplied is empty!", false));
885 }
886 memcached_return_t rc= memcached_delete_by_key(&memc,
887 master_key.c_str(),
888 master_key.length(),
889 key.c_str(),
890 key.length(),
891 expiration);
892 return (rc == MEMCACHED_SUCCESS);
893 }
894
895 /**
896 * Wipe the contents of memcached servers.
897 *
898 * @param[in] expiration time to wait until wiping contents of
899 * memcached servers
900 * @return true on success; false otherwise
901 */
902 bool flush(time_t expiration)
903 {
904 memcached_return_t rc= memcached_flush(&memc, expiration);
905 return (rc == MEMCACHED_SUCCESS);
906 }
907
908 /**
909 * Callback function for result sets. It passes the result
910 * sets to the list of functions provided.
911 *
912 * @param[in] callback list of callback functions
913 * @param[in] context pointer to memory reference that is
914 * supplied to the calling function
915 * @param[in] num_of_callbacks number of callback functions
916 * @return true on success; false otherwise
917 */
918 bool fetchExecute(memcached_execute_fn *callback,
919 void *context,
920 uint32_t num_of_callbacks)
921 {
922 memcached_return_t rc= memcached_fetch_execute(&memc,
923 callback,
924 context,
925 num_of_callbacks);
926 return (rc == MEMCACHED_SUCCESS);
927 }
928
929 /**
930 * Get the library version string.
931 * @return std::string containing a copy of the library version string.
932 */
933 const std::string libVersion() const
934 {
935 const char *ver= memcached_lib_version();
936 const std::string version(ver);
937 return version;
938 }
939
940 /**
941 * Retrieve memcached statistics. Populate a std::map with the retrieved
942 * stats. Each server will map to another std::map of the key:value stats.
943 *
944 * @param[out] stats_map a std::map to be populated with the memcached
945 * stats
946 * @return true on success; false otherwise
947 */
948 bool getStats(std::map< std::string, std::map<std::string, std::string> >
949 &stats_map)
950 {
951 memcached_return_t rc;
952 memcached_stat_st *stats= memcached_stat(&memc, NULL, &rc);
953
954 if (rc != MEMCACHED_SUCCESS &&
955 rc != MEMCACHED_SOME_ERRORS)
956 {
957 return false;
958 }
959
960 uint32_t server_count= memcached_server_count(&memc);
961
962 /*
963 * For each memcached server, construct a std::map for its stats and add
964 * it to the std::map of overall stats.
965 */
966 for (uint32_t x= 0; x < server_count; x++)
967 {
968 std::ostringstream strstm;
969 std::string server_name(memcached_server_name(&memc, servers[x]));
970 server_name.append(":");
971 strstm << memcached_server_port(&memc, servers[x]);
972 server_name.append(strstm.str());
973
974 std::map<std::string, std::string> server_stats;
975 char **list= NULL;
976 char **ptr= NULL;
977
978 list= memcached_stat_get_keys(&memc, &stats[x], &rc);
979 for (ptr= list; *ptr; ptr++)
980 {
981 char *value= memcached_stat_get_value(&memc, &stats[x], *ptr, &rc);
982 server_stats[*ptr]= value;
983 free(value);
984 }
985
986 stats_map[server_name]= server_stats;
987 free(list);
988 }
989
990 memcached_stat_free(&memc, stats);
991 return true;
992 }
993
994 private:
995
996 std::string servers_list;
997 memcached_st memc;
998 memcached_server_st *servers;
999 memcached_result_st result;
1000 };
1001
1002 }
1003
1004 #endif /* LIBMEMCACHEDPP_H */