1Cache::Memcached(3) User Contributed Perl Documentation Cache::Memcached(3)
2
6 Cache::Memcached - client library for memcached (memory cache daemon)
7
9 use Cache::Memcached;
10 $memd = new Cache::Memcached {
12 'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212", "/var/sock/memcached",
13 "10.0.0.17:11211", [ "10.0.0.17:11211", 3 ] ],
14 'debug' => 0,
15 'compress_threshold' => 10_000,
16 };
17 $memd->set_servers($array_ref);
18 $memd->set_compress_threshold(10_000);
19 $memd->enable_compress(0);
20 $memd->set("my_key", "Some value");
22 $memd->set("object_key", { 'complex' => [ "object", 2, 4 ]});
23 $val = $memd->get("my_key");
25 $val = $memd->get("object_key");
26 if ($val) { print $val->{'complex'}->[2]; }
27 $memd->incr("key");
29 $memd->decr("key");
30 $memd->incr("key", 2);
31
33 This is the Perl API for memcached, a distributed memory cache daemon.
34 More information is available at:
35 http://www.danga.com/memcached/
37
39 "new"
40 Takes one parameter, a hashref of options. The most important key
41 is "servers", but that can also be set later with the "set_servers"
42 method. The servers must be an arrayref of hosts, each of which is
43 either a scalar of the form "10.0.0.10:11211" or an arrayref of the
44 former and an integer weight value. (The default weight if
45 unspecified is 1.) It's recommended that weight values be kept as
46 low as possible, as this module currently allocates memory for
47 bucket distribution proportional to the total host weights.
48 Use "compress_threshold" to set a compression threshold, in bytes.
50 Values larger than this threshold will be compressed by "set" and
51 decompressed by "get".
52 Use "no_rehash" to disable finding a new memcached server when one
54 goes down. Your application may or may not need this, depending on
55 your expirations and key usage.
56 Use "readonly" to disable writes to backend memcached servers.
58 Only get and get_multi will work. This is useful in bizarre debug
59 and profiling cases only.
60 Use "namespace" to prefix all keys with the provided namespace
62 value. That is, if you set namespace to "app1:" and later do a set
63 of "foo" to "bar", memcached is actually seeing you set "app1:foo"
64 to "bar".
65 The other useful key is "debug", which when set to true will
67 produce diagnostics on STDERR.
68
70 "set_servers"
71 Sets the server list this module distributes key gets and sets
72 between. The format is an arrayref of identical form as described
73 in the "new" constructor.
74 "set_debug"
76 Sets the "debug" flag. See "new" constructor for more information.
77 "set_readonly"
79 Sets the "readonly" flag. See "new" constructor for more
80 information.
81 "set_norehash"
83 Sets the "no_rehash" flag. See "new" constructor for more
84 information.
85 "set_compress_threshold"
87 Sets the compression threshold. See "new" constructor for more
88 information.
89 "enable_compress"
91 Temporarily enable or disable compression. Has no effect if
92 "compress_threshold" isn't set, but has an overriding effect if it
93 is.
94 "get"
96 my $val = $memd->get($key);
97 Retrieves a key from the memcache. Returns the value
99 (automatically thawed with Storable, if necessary) or undef.
100 The $key can optionally be an arrayref, with the first element
102 being the hash value, if you want to avoid making this module
103 calculate a hash value. You may prefer, for example, to keep all
104 of a given user's objects on the same memcache server, so you could
105 use the user's unique id as the hash value.
106 "get_multi"
108 my $hashref = $memd->get_multi(@keys);
109 Retrieves multiple keys from the memcache doing just one query.
111 Returns a hashref of key/value pairs that were available.
112 This method is recommended over regular 'get' as it lowers the
114 number of total packets flying around your network, reducing total
115 latency, since your app doesn't have to wait for each round-trip of
116 'get' before sending the next one.
117 "set"
119 $memd->set($key, $value[, $exptime]);
120 Unconditionally sets a key to a given value in the memcache.
122 Returns true if it was stored successfully.
123 The $key can optionally be an arrayref, with the first element
125 being the hash value, as described above.
126 The $exptime (expiration time) defaults to "never" if unspecified.
128 If you want the key to expire in memcached, pass an integer
129 $exptime. If value is less than 60*60*24*30 (30 days), time is
130 assumed to be relative from the present. If larger, it's
131 considered an absolute Unix time.
132 "add"
134 $memd->add($key, $value[, $exptime]);
135 Like "set", but only stores in memcache if the key doesn't already
137 exist.
138 "replace"
140 $memd->replace($key, $value[, $exptime]);
141 Like "set", but only stores in memcache if the key already exists.
143 The opposite of "add".
144 "delete"
146 $memd->delete($key[, $time]);
147 Deletes a key. You may optionally provide an integer time value
149 (in seconds) to tell the memcached server to block new writes to
150 this key for that many seconds. (Sometimes useful as a hacky means
151 to prevent races.) Returns true if key was found and deleted, and
152 false otherwise.
153 You may also use the alternate method name remove, so
155 Cache::Memcached looks like the Cache::Cache API.
156 "incr"
158 $memd->incr($key[, $value]);
159 Sends a command to the server to atomically increment the value for
161 $key by $value, or by 1 if $value is undefined. Returns undef if
162 $key doesn't exist on server, otherwise it returns the new value
163 after incrementing. Value should be zero or greater. Overflow on
164 server is not checked. Be aware of values approaching 2**32. See
165 decr.
166 "decr"
168 $memd->decr($key[, $value]);
169 Like incr, but decrements. Unlike incr, underflow is checked and
171 new values are capped at 0. If server value is 1, a decrement of 2
172 returns 0, not -1.
173 "stats"
175 $memd->stats([$keys]);
176 Returns a hashref of statistical data regarding the memcache
178 server(s), the $memd object, or both. $keys can be an arrayref of
179 keys wanted, a single key wanted, or absent (in which case the
180 default value is malloc, sizes, self, and the empty string). These
181 keys are the values passed to the 'stats' command issued to the
182 memcached server(s), except for 'self' which is internal to the
183 $memd object. Allowed values are:
184 "misc"
186 The stats returned by a 'stats' command: pid, uptime, version,
187 bytes, get_hits, etc.
188 "malloc"
190 The stats returned by a 'stats malloc': total_alloc,
191 arena_size, etc.
192 "sizes"
194 The stats returned by a 'stats sizes'.
195 "self"
197 The stats for the $memd object itself (a copy of
198 $memd->{'stats'}).
199 "maps"
201 The stats returned by a 'stats maps'.
202 "cachedump"
204 The stats returned by a 'stats cachedump'.
205 "slabs"
207 The stats returned by a 'stats slabs'.
208 "items"
210 The stats returned by a 'stats items'.
211 "disconnect_all"
213 $memd->disconnect_all;
214 Closes all cached sockets to all memcached servers. You must do
216 this if your program forks and the parent has used this module at
217 all. Otherwise the children will try to use cached sockets and
218 they'll fight (as children do) and garble the client/server
219 protocol.
220 "flush_all"
222 $memd->flush_all;
223 Runs the memcached "flush_all" command on all configured hosts,
225 emptying all their caches. (or rather, invalidating all items in
226 the caches in an O(1) operation...) Running stats will still show
227 the item existing, they're just be non-existent and lazily
228 destroyed next time you try to detch any of them.
229
231 When a server goes down, this module does detect it, and re-hashes the
232 request to the remaining servers, but the way it does it isn't very
233 clean. The result may be that it gives up during its rehashing and
234 refuses to get/set something it could've, had it been done right.
235
237 This module is Copyright (c) 2003 Brad Fitzpatrick. All rights
238 reserved.
239 You may distribute under the terms of either the GNU General Public
241 License or the Artistic License, as specified in the Perl README file.
242
244 This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
245
247 See the memcached website:
248 http://www.danga.com/memcached/
249
251 Brad Fitzpatrick <brad@danga.com>
252 Anatoly Vorobey <mellon@pobox.com>
254 Brad Whitaker <whitaker@danga.com>
256 Jamie McCarthy <jamie@mccarthy.vg>
258perl v5.12.0 2009-10-21 Cache::Memcached(3)