X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=libmemcached%2Fmemcached.hpp;h=d7086b4ce301ea11a876fdcb3a20f8b0831a009a;hb=a7a011c2ea4a63368b3a96a332da00820ed402cb;hp=3b40304234167f8238c0f0136cf5c277cb31a0cd;hpb=5ab7cb84b990a19ab832abd42985b0b79b9172f2;p=m6w6%2Flibmemcached diff --git a/libmemcached/memcached.hpp b/libmemcached/memcached.hpp index 3b403042..d7086b4c 100644 --- a/libmemcached/memcached.hpp +++ b/libmemcached/memcached.hpp @@ -16,9 +16,11 @@ #define LIBMEMCACHEDPP_H #include +#include #include +#include #include #include #include @@ -36,15 +38,49 @@ public: Memcache() : + servers_list(), memc(), + servers(NULL), result() { memcached_create(&memc); } + Memcache(const std::string &in_servers_list) + : + servers_list(in_servers_list), + memc(), + servers(NULL), + result() + { + memcached_create(&memc); + servers= memcached_servers_parse(servers_list.c_str()); + memcached_server_push(&memc, servers); + } + + Memcache(const std::string &hostname, + unsigned int port) + : + servers_list(), + memc(), + servers(NULL), + result() + { + memcached_create(&memc); + servers_list.append(hostname); + servers_list.append(":"); + std::ostringstream strsmt; + strsmt << port; + servers_list.append(strsmt.str()); + servers= memcached_servers_parse(servers_list.c_str()); + memcached_server_push(&memc, servers); + } + Memcache(memcached_st *clone) : + servers_list(), memc(), + servers(NULL), result() { memcached_clone(&memc, clone); @@ -52,15 +88,31 @@ public: Memcache(const Memcache &rhs) : + servers_list(rhs.servers_list), memc(), + servers(NULL), result() { memcached_clone(&memc, const_cast(&rhs.getImpl())); + servers= memcached_servers_parse(servers_list.c_str()); + memcached_server_push(&memc, servers); + } + + Memcache &operator=(const Memcache &rhs) + { + if (this != &rhs) + { + memcached_clone(&memc, const_cast(&rhs.getImpl())); + servers= memcached_servers_parse(servers_list.c_str()); + memcached_server_push(&memc, servers); + } + return *this; } ~Memcache() { memcached_free(&memc); + memcached_server_list_free(servers); } /** @@ -92,14 +144,85 @@ public: } /** - * Fetches an individual value from the server. + * Return the string which contains the list of memcached servers being + * used. + * + * @return a std::string containing the list of memcached servers + */ + const std::string getServersList() const + { + return servers_list; + } + + /** + * Set the list of memcached servers to use. + * + * @param[in] in_servers_list list of servers + * @return true on success; false otherwise + */ + bool setServers(const std::string &in_servers_list) + { + servers_list.assign(in_servers_list); + servers= memcached_servers_parse(in_servers_list.c_str()); + memcached_server_push(&memc, servers); + return (servers == NULL); + } + + /** + * Add a server to the list of memcached servers to use. + * + * @param[in] server_name name of the server to add + * @param[in] port port number of server to add + * @return true on success; false otherwise + */ + bool addServer(const std::string &server_name, unsigned int port) + { + memcached_return rc; + std::ostringstream strstm; + servers_list.append(","); + servers_list.append(server_name); + servers_list.append(":"); + strstm << port; + servers_list.append(strstm.str()); + servers= memcached_server_list_append(servers, + server_name.c_str(), + port, + &rc); + memcached_server_push(&memc, servers); + return (rc == MEMCACHED_SUCCESS); + } + + /** + * Remove a server from the list of memcached servers to use. + * + * @param[in] server_name name of the server to remove + * @param[in] port port number of server to remove + * @return true on success; false otherwise + */ + bool removeServer(const std::string &server_name, size_t port) + { + std::string tmp_str; + std::ostringstream strstm; + tmp_str.append(","); + tmp_str.append(server_name); + tmp_str.append(":"); + strstm << port; + tmp_str.append(strstm.str()); + memcached_server_st *server= memcached_servers_parse(tmp_str.c_str()); + memcached_return rc= memcached_server_remove(server); + return (rc == MEMCACHED_SUCCESS); + } + + /** + * Fetches an individual value from the server. mget() must always + * be called before using this method. * * @param[in] key key of object to fetch * @param[out] ret_val store returned object in this vector - * @return true on success; false on failure + * @return a memcached return structure */ - bool fetch(std::string &key, - std::vector &ret_val) + memcached_return fetch(std::string &key, + std::vector &ret_val) { char ret_key[MEMCACHED_MAX_KEY]; size_t value_length= 0; @@ -113,13 +236,26 @@ public: ret_val.reserve(value_length); ret_val.assign(value, value + value_length); key.assign(ret_key); - return true; + free(value); } - return false; + else if (value) + { + free(value); + } + + return rc; } - std::vector &get(const std::string &key, - std::vector &ret_val) + /** + * Fetches an individual value from the server. + * + * @param[in] key key of object whose value to get + * @param[out] ret_val object that is retrieved is stored in + * this vector + * @return true on success; false otherwise + */ + bool get(const std::string &key, + std::vector &ret_val) throw (Error) { uint32_t flags= 0; memcached_return rc; @@ -127,7 +263,7 @@ public: if (key.empty()) { - return ret_val; + throw(Error("the key supplied is empty!", false)); } char *value= memcached_get(&memc, key.c_str(), key.length(), &value_length, &flags, &rc); @@ -135,13 +271,27 @@ public: { ret_val.reserve(value_length); ret_val.assign(value, value + value_length); + free(value); + return true; } - return ret_val; + return false; } - std::vector &getByKey(const std::string &master_key, - const std::string &key, - std::vector &ret_val) + /** + * Fetches an individual from a server which is specified by + * the master_key parameter that is used for determining which + * server an object was stored in if key partitioning was + * used for storage. + * + * @param[in] master_key key that specifies server object is stored on + * @param[in] key key of object whose value to get + * @param[out] ret_val object that is retrieved is stored in + * this vector + * @return true on success; false otherwise + */ + bool getByKey(const std::string &master_key, + const std::string &key, + std::vector &ret_val) throw(Error) { uint32_t flags= 0; memcached_return rc; @@ -149,20 +299,29 @@ public: if (master_key.empty() || key.empty()) { - return ret_val; + throw(Error("the master key or key supplied is empty!", false)); } - char *value= memcached_get_by_key(&memc, - master_key.c_str(), master_key.length(), + char *value= memcached_get_by_key(&memc, + master_key.c_str(), master_key.length(), key.c_str(), key.length(), &value_length, &flags, &rc); if (value) { ret_val.reserve(value_length); ret_val.assign(value, value + value_length); + free(value); + return true; } - return ret_val; + return false; } + /** + * Selects multiple keys at once. This method always + * works asynchronously. + * + * @param[in] keys vector of keys to select + * @return true if all keys are found + */ bool mget(std::vector &keys) { std::vector real_keys; @@ -199,30 +358,83 @@ public: return false; } - bool set(const std::string &key, + /** + * Writes an object to the server. If the object already exists, it will + * overwrite the existing object. This method always returns true + * when using non-blocking mode unless a network error occurs. + * + * @param[in] key key of object to write to server + * @param[in] value value of object to write to server + * @param[in] expiration time to keep the object stored in the server for + * @param[in] flags flags to store with the object + * @return true on succcess; false otherwise + */ + bool set(const std::string &key, const std::vector &value, time_t expiration, - uint32_t flags) + uint32_t flags) throw(Error) { if (key.empty() || value.empty()) { - return false; + throw(Error("the key or value supplied is empty!", false)); } - memcached_return rc= memcached_set(&memc, + memcached_return rc= memcached_set(&memc, key.c_str(), key.length(), &value[0], value.size(), expiration, flags); return (rc == MEMCACHED_SUCCESS || rc == MEMCACHED_BUFFERED); } + /** + * Writes an object to a server specified by the master_key parameter. + * If the object already exists, it will overwrite the existing object. + * + * @param[in] master_key key that specifies server to write to + * @param[in] key key of object to write to server + * @param[in] value value of object to write to server + * @param[in] expiration time to keep the object stored in the server for + * @param[in] flags flags to store with the object + * @return true on succcess; false otherwise + */ + bool setByKey(const std::string &master_key, + const std::string &key, + const std::vector &value, + time_t expiration, + uint32_t flags) throw(Error) + { + if (master_key.empty() || + key.empty() || + value.empty()) + { + throw(Error("the key or value supplied is empty!", false)); + } + memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(), + master_key.length(), + key.c_str(), key.length(), + &value[0], value.size(), + expiration, + flags); + return (rc == MEMCACHED_SUCCESS); + } + + /** + * Writes a list of objects to the server. Objects are specified by + * 2 vectors - 1 vector of keys and 1 vector of values. + * + * @param[in] keys vector of keys of objects to write to server + * @param[in] values vector of values of objects to write to server + * @param[in] expiration time to keep the objects stored in server for + * @param[in] flags flags to store with the objects + * @return true on success; false otherwise + */ bool setAll(std::vector &keys, std::vector< std::vector *> &values, time_t expiration, - uint32_t flags) + uint32_t flags) throw(Error) { if (keys.size() != values.size()) { - return false; + throw(Error("The number of keys and values do not match!", false)); } bool retval= true; std::vector::iterator key_it= keys.begin(); @@ -240,13 +452,22 @@ public: return retval; } + /** + * Writes a list of objects to the server. Objects are specified by + * a map of keys to values. + * + * @param[in] key_value_map map of keys and values to store in server + * @param[in] expiration time to keep the objects stored in server for + * @param[in] flags flags to store with the objects + * @return true on success; false otherwise + */ bool setAll(std::map > &key_value_map, time_t expiration, - uint32_t flags) + uint32_t flags) throw(Error) { if (key_value_map.empty()) { - return false; + throw(Error("The key/values are not properly set!", false)); } bool retval= true; std::map >::iterator it= @@ -256,50 +477,52 @@ public: retval= set(it->first, it->second, expiration, flags); if (retval == false) { - return false; + std::string err_buff("There was an error setting the key "); + err_buff.append(it->first); + throw(Error(err_buff, false)); } ++it; } return true; } - bool setByKey(const std::string &master_key, - const std::string &key, - const std::vector &value, - time_t expiration, - uint32_t flags) - { - if (master_key.empty() || - key.empty() || - value.empty()) - { - return false; - } - memcached_return rc= memcached_set_by_key(&memc, master_key.c_str(), - master_key.length(), - key.c_str(), key.length(), - &value[0], value.size(), - expiration, - flags); - return (rc == MEMCACHED_SUCCESS); - } - - bool increment(const std::string &key, unsigned int offset, uint64_t *value) + /** + * Increment the value of the object associated with the specified + * key by the offset given. The resulting value is saved in the value + * parameter. + * + * @param[in] key key of object in server whose value to increment + * @param[in] offset amount to increment object's value by + * @param[out] value store the result of the increment here + * @return true on success; false otherwise + */ + bool increment(const std::string &key, uint32_t offset, uint64_t *value) throw(Error) { if (key.empty()) { - return false; + throw(Error("the key supplied is empty!", false)); } memcached_return rc= memcached_increment(&memc, key.c_str(), key.length(), offset, value); return (rc == MEMCACHED_SUCCESS); } - bool decrement(const std::string &key, unsigned int offset, uint64_t *value) + /** + * Decrement the value of the object associated with the specified + * key by the offset given. The resulting value is saved in the value + * parameter. + * + * @param[in] key key of object in server whose value to decrement + * @param[in] offset amount to increment object's value by + * @param[out] value store the result of the decrement here + * @return true on success; false otherwise + */ + bool decrement(const std::string &key, uint32_t offset, uint64_t *value) + throw(Error) { if (key.empty()) { - return false; + throw(Error("the key supplied is empty!", false)); } memcached_return rc= memcached_decrement(&memc, key.c_str(), key.length(), @@ -308,26 +531,45 @@ public: } + /** + * Add an object with the specified key and value to the server. This + * function returns false if the object already exists on the server. + * + * @param[in] key key of object to add + * @param[in] value of object to add + * @return true on success; false otherwise + */ bool add(const std::string &key, const std::vector &value) + throw(Error) { if (key.empty() || value.empty()) { - return false; + throw(Error("the key or value supplied is empty!", false)); } memcached_return rc= memcached_add(&memc, key.c_str(), key.length(), &value[0], value.size(), 0, 0); return (rc == MEMCACHED_SUCCESS); } + /** + * Add an object with the specified key and value to the server. This + * function returns false if the object already exists on the server. The + * server to add the object to is specified by the master_key parameter. + * + * @param[in[ master_key key of server to add object to + * @param[in] key key of object to add + * @param[in] value of object to add + * @return true on success; false otherwise + */ bool addByKey(const std::string &master_key, const std::string &key, - const std::vector &value) + const std::vector &value) throw(Error) { if (master_key.empty() || key.empty() || value.empty()) { - return false; + throw(Error("the master key or key supplied is empty!", false)); } memcached_return rc= memcached_add_by_key(&memc, master_key.c_str(), @@ -340,12 +582,20 @@ public: return (rc == MEMCACHED_SUCCESS); } - bool replace(const std::string &key, const std::vector &value) + /** + * Replaces an object on the server. This method only succeeds + * if the object is already present on the server. + * + * @param[in] key key of object to replace + * @param[in[ value value to replace object with + * @return true on success; false otherwise + */ + bool replace(const std::string &key, const std::vector &value) throw(Error) { if (key.empty() || value.empty()) { - return false; + throw(Error("the key or value supplied is empty!", false)); } memcached_return rc= memcached_replace(&memc, key.c_str(), key.length(), &value[0], value.size(), @@ -353,6 +603,16 @@ public: return (rc == MEMCACHED_SUCCESS); } + /** + * Replaces an object on the server. This method only succeeds + * if the object is already present on the server. The server + * to replace the object on is specified by the master_key param. + * + * @param[in] master_key key of server to replace object on + * @param[in] key key of object to replace + * @param[in[ value value to replace object with + * @return true on success; false otherwise + */ bool replaceByKey(const std::string &master_key, const std::string &key, const std::vector &value) @@ -361,7 +621,7 @@ public: key.empty() || value.empty()) { - return false; + throw(Error("the master key or key supplied is empty!", false)); } memcached_return rc= memcached_replace_by_key(&memc, master_key.c_str(), @@ -374,63 +634,101 @@ public: return (rc == MEMCACHED_SUCCESS); } + /** + * Places a segment of data before the last piece of data stored. + * + * @param[in] key key of object whose value we will prepend data to + * @param[in] value data to prepend to object's value + * @return true on success; false otherwise + */ bool prepend(const std::string &key, const std::vector &value) + throw(Error) { if (key.empty() || value.empty()) { - return false; + throw(Error("the key or value supplied is empty!", false)); } memcached_return rc= memcached_prepend(&memc, key.c_str(), key.length(), &value[0], value.size(), 0, 0); return (rc == MEMCACHED_SUCCESS); } + /** + * Places a segment of data before the last piece of data stored. The + * server on which the object where we will be prepending data is stored + * on is specified by the master_key parameter. + * + * @param[in] master_key key of server where object is stored + * @param[in] key key of object whose value we will prepend data to + * @param[in] value data to prepend to object's value + * @return true on success; false otherwise + */ bool prependByKey(const std::string &master_key, const std::string &key, const std::vector &value) + throw(Error) { if (master_key.empty() || key.empty() || value.empty()) { - return false; + throw(Error("the master key or key supplied is empty!", false)); } - memcached_return rc= memcached_prepend_by_key(&memc, - master_key.c_str(), + memcached_return rc= memcached_prepend_by_key(&memc, + master_key.c_str(), master_key.length(), - key.c_str(), + key.c_str(), key.length(), - &value[0], + &value[0], value.size(), 0, 0); return (rc == MEMCACHED_SUCCESS); } + /** + * Places a segment of data at the end of the last piece of data stored. + * + * @param[in] key key of object whose value we will append data to + * @param[in] value data to append to object's value + * @return true on success; false otherwise + */ bool append(const std::string &key, const std::vector &value) + throw(Error) { if (key.empty() || value.empty()) { - return false; + throw(Error("the key or value supplied is empty!", false)); } - memcached_return rc= memcached_append(&memc, - key.c_str(), + memcached_return rc= memcached_append(&memc, + key.c_str(), key.length(), - &value[0], - value.size(), + &value[0], + value.size(), 0, 0); return (rc == MEMCACHED_SUCCESS); } - bool appendByKey(const std::string &master_key, - const std::string &key, + /** + * Places a segment of data at the end of the last piece of data stored. The + * server on which the object where we will be appending data is stored + * on is specified by the master_key parameter. + * + * @param[in] master_key key of server where object is stored + * @param[in] key key of object whose value we will append data to + * @param[in] value data to append to object's value + * @return true on success; false otherwise + */ + bool appendByKey(const std::string &master_key, + const std::string &key, const std::vector &value) + throw(Error) { if (master_key.empty() || key.empty() || value.empty()) { - return false; + throw(Error("the master key or key supplied is empty!", false)); } memcached_return rc= memcached_append_by_key(&memc, master_key.c_str(), @@ -443,13 +741,21 @@ public: return (rc == MEMCACHED_SUCCESS); } + /** + * Overwrite data in the server as long as the cas_arg value + * is still the same in the server. + * + * @param[in] key key of object in server + * @param[in] value value to store for object in server + * @param[in] cas_arg "cas" value + */ bool cas(const std::string &key, const std::vector &value, - uint64_t cas_arg) + uint64_t cas_arg) throw(Error) { if (key.empty() || value.empty()) { - return false; + throw(Error("the key or value supplied is empty!", false)); } memcached_return rc= memcached_cas(&memc, key.c_str(), key.length(), &value[0], value.size(), @@ -457,16 +763,26 @@ public: return (rc == MEMCACHED_SUCCESS); } + /** + * Overwrite data in the server as long as the cas_arg value + * is still the same in the server. The server to use is + * specified by the master_key parameter. + * + * @param[in] master_key specifies server to operate on + * @param[in] key key of object in server + * @param[in] value value to store for object in server + * @param[in] cas_arg "cas" value + */ bool casByKey(const std::string &master_key, const std::string &key, const std::vector &value, - uint64_t cas_arg) + uint64_t cas_arg) throw(Error) { if (master_key.empty() || key.empty() || value.empty()) { - return false; + throw(Error("the master key, key or value supplied is empty!", false)); } memcached_return rc= memcached_cas_by_key(&memc, master_key.c_str(), @@ -479,38 +795,114 @@ public: return (rc == MEMCACHED_SUCCESS); } - bool remove(const std::string &key) + /** + * Delete an object from the server specified by the key given. + * + * @param[in] key key of object to delete + * @return true on success; false otherwise + */ + bool remove(const std::string &key) throw(Error) { if (key.empty()) { - return false; + throw(Error("the key supplied is empty!", false)); } memcached_return rc= memcached_delete(&memc, key.c_str(), key.length(), 0); return (rc == MEMCACHED_SUCCESS); } + /** + * Delete an object from the server specified by the key given. + * + * @param[in] key key of object to delete + * @param[in] expiration time to delete the object after + * @return true on success; false otherwise + */ + bool remove(const std::string &key, + time_t expiration) throw(Error) + { + if (key.empty()) + { + throw(Error("the key supplied is empty!", false)); + } + memcached_return rc= memcached_delete(&memc, + key.c_str(), + key.length(), + expiration); + return (rc == MEMCACHED_SUCCESS); + } + + /** + * Delete an object from the server specified by the key given. + * + * @param[in] master_key specifies server to remove object from + * @param[in] key key of object to delete + * @return true on success; false otherwise + */ + bool removeByKey(const std::string &master_key, + const std::string &key) throw(Error) + { + if (master_key.empty() || key.empty()) + { + throw(Error("the master key or key supplied is empty!", false)); + } + memcached_return rc= memcached_delete_by_key(&memc, + master_key.c_str(), + master_key.length(), + key.c_str(), + key.length(), + 0); + return (rc == MEMCACHED_SUCCESS); + } + + /** + * Delete an object from the server specified by the key given. + * + * @param[in] master_key specifies server to remove object from + * @param[in] key key of object to delete + * @param[in] expiration time to delete the object after + * @return true on success; false otherwise + */ bool removeByKey(const std::string &master_key, - const std::string &key) + const std::string &key, + time_t expiration) throw(Error) { if (master_key.empty() || key.empty()) { - return false; + throw(Error("the master key or key supplied is empty!", false)); } memcached_return rc= memcached_delete_by_key(&memc, master_key.c_str(), master_key.length(), key.c_str(), key.length(), - 0); + expiration); return (rc == MEMCACHED_SUCCESS); } + /** + * Wipe the contents of memcached servers. + * + * @param[in] expiration time to wait until wiping contents of + * memcached servers + * @return true on success; false otherwise + */ bool flush(time_t expiration) { memcached_return rc= memcached_flush(&memc, expiration); return (rc == MEMCACHED_SUCCESS); } + /** + * Callback function for result sets. It passes the result + * sets to the list of functions provided. + * + * @param[in] callback list of callback functions + * @param[in] context pointer to memory reference that is + * supplied to the calling function + * @param[in] num_of_callbacks number of callback functions + * @return true on success; false otherwise + */ bool fetchExecute(memcached_execute_function *callback, void *context, unsigned int num_of_callbacks) @@ -533,9 +925,65 @@ public: return version; } + /** + * Retrieve memcached statistics. Populate a std::map with the retrieved + * stats. Each server will map to another std::map of the key:value stats. + * + * @param[out] stats_map a std::map to be populated with the memcached + * stats + * @return true on success; false otherwise + */ + bool getStats(std::map< std::string, std::map > + &stats_map) + { + memcached_return rc; + memcached_stat_st *stats= memcached_stat(&memc, NULL, &rc); + + if (rc != MEMCACHED_SUCCESS && + rc != MEMCACHED_SOME_ERRORS) + { + return false; + } + + uint32_t server_count= memcached_server_count(&memc); + + /* + * For each memcached server, construct a std::map for its stats and add + * it to the std::map of overall stats. + */ + for (uint32_t x= 0; x < server_count; x++) + { + std::ostringstream strstm; + std::string server_name(memcached_server_name(&memc, servers[x])); + server_name.append(":"); + strstm << memcached_server_port(&memc, servers[x]); + server_name.append(strstm.str()); + + std::map server_stats; + char **list= NULL; + char **ptr= NULL; + + list= memcached_stat_get_keys(&memc, &stats[x], &rc); + for (ptr= list; *ptr; ptr++) + { + char *value= memcached_stat_get_value(&memc, &stats[x], *ptr, &rc); + server_stats[*ptr]= value; + free(value); + } + + stats_map[server_name]= server_stats; + free(list); + } + + memcached_stat_free(&memc, stats); + return true; + } + private: + std::string servers_list; memcached_st memc; + memcached_server_st *servers; memcached_result_st result; };