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 Use "connect_timeout" and "select_timeout" to set connection and
67 polling timeouts. The "connect_timeout" defaults to .25 second, and
68 the "select_timeout" defaults to 1 second.
69 The other useful key is "debug", which when set to true will
71 produce diagnostics on STDERR.
72
74 "set_servers"
75 Sets the server list this module distributes key gets and sets
76 between. The format is an arrayref of identical form as described
77 in the "new" constructor.
78 "set_debug"
80 Sets the "debug" flag. See "new" constructor for more information.
81 "set_readonly"
83 Sets the "readonly" flag. See "new" constructor for more
84 information.
85 "set_norehash"
87 Sets the "no_rehash" flag. See "new" constructor for more
88 information.
89 "set_compress_threshold"
91 Sets the compression threshold. See "new" constructor for more
92 information.
93 "set_connect_timeout"
95 Sets the connect timeout. See "new" constructor for more
96 information.
97 "set_select_timeout"
99 Sets the select timeout. See "new" constructor for more
100 information.
101 "enable_compress"
103 Temporarily enable or disable compression. Has no effect if
104 "compress_threshold" isn't set, but has an overriding effect if it
105 is.
106 "get"
108 my $val = $memd->get($key);
109 Retrieves a key from the memcache. Returns the value
111 (automatically thawed with Storable, if necessary) or undef.
112 The $key can optionally be an arrayref, with the first element
114 being the hash value, if you want to avoid making this module
115 calculate a hash value. You may prefer, for example, to keep all
116 of a given user's objects on the same memcache server, so you could
117 use the user's unique id as the hash value.
118 "get_multi"
120 my $hashref = $memd->get_multi(@keys);
121 Retrieves multiple keys from the memcache doing just one query.
123 Returns a hashref of key/value pairs that were available.
124 This method is recommended over regular 'get' as it lowers the
126 number of total packets flying around your network, reducing total
127 latency, since your app doesn't have to wait for each round-trip of
128 'get' before sending the next one.
129 "set"
131 $memd->set($key, $value[, $exptime]);
132 Unconditionally sets a key to a given value in the memcache.
134 Returns true if it was stored successfully.
135 The $key can optionally be an arrayref, with the first element
137 being the hash value, as described above.
138 The $exptime (expiration time) defaults to "never" if unspecified.
140 If you want the key to expire in memcached, pass an integer
141 $exptime. If value is less than 60*60*24*30 (30 days), time is
142 assumed to be relative from the present. If larger, it's
143 considered an absolute Unix time.
144 "add"
146 $memd->add($key, $value[, $exptime]);
147 Like "set", but only stores in memcache if the key doesn't already
149 exist.
150 "replace"
152 $memd->replace($key, $value[, $exptime]);
153 Like "set", but only stores in memcache if the key already exists.
155 The opposite of "add".
156 "delete"
158 $memd->delete($key[, $time]);
159 Deletes a key. You may optionally provide an integer time value
161 (in seconds) to tell the memcached server to block new writes to
162 this key for that many seconds. (Sometimes useful as a hacky means
163 to prevent races.) Returns true if key was found and deleted, and
164 false otherwise.
165 You may also use the alternate method name remove, so
167 Cache::Memcached looks like the Cache::Cache API.
168 "incr"
170 $memd->incr($key[, $value]);
171 Sends a command to the server to atomically increment the value for
173 $key by $value, or by 1 if $value is undefined. Returns undef if
174 $key doesn't exist on server, otherwise it returns the new value
175 after incrementing. Value should be zero or greater. Overflow on
176 server is not checked. Be aware of values approaching 2**32. See
177 decr.
178 "decr"
180 $memd->decr($key[, $value]);
181 Like incr, but decrements. Unlike incr, underflow is checked and
183 new values are capped at 0. If server value is 1, a decrement of 2
184 returns 0, not -1.
185 "stats"
187 $memd->stats([$keys]);
188 Returns a hashref of statistical data regarding the memcache
190 server(s), the $memd object, or both. $keys can be an arrayref of
191 keys wanted, a single key wanted, or absent (in which case the
192 default value is malloc, sizes, self, and the empty string). These
193 keys are the values passed to the 'stats' command issued to the
194 memcached server(s), except for 'self' which is internal to the
195 $memd object. Allowed values are:
196 "misc"
198 The stats returned by a 'stats' command: pid, uptime, version,
199 bytes, get_hits, etc.
200 "malloc"
202 The stats returned by a 'stats malloc': total_alloc,
203 arena_size, etc.
204 "sizes"
206 The stats returned by a 'stats sizes'.
207 "self"
209 The stats for the $memd object itself (a copy of
210 $memd->{'stats'}).
211 "maps"
213 The stats returned by a 'stats maps'.
214 "cachedump"
216 The stats returned by a 'stats cachedump'.
217 "slabs"
219 The stats returned by a 'stats slabs'.
220 "items"
222 The stats returned by a 'stats items'.
223 "disconnect_all"
225 $memd->disconnect_all;
226 Closes all cached sockets to all memcached servers. You must do
228 this if your program forks and the parent has used this module at
229 all. Otherwise the children will try to use cached sockets and
230 they'll fight (as children do) and garble the client/server
231 protocol.
232 "flush_all"
234 $memd->flush_all;
235 Runs the memcached "flush_all" command on all configured hosts,
237 emptying all their caches. (or rather, invalidating all items in
238 the caches in an O(1) operation...) Running stats will still show
239 the item existing, they're just be non-existent and lazily
240 destroyed next time you try to detch any of them.
241
243 When a server goes down, this module does detect it, and re-hashes the
244 request to the remaining servers, but the way it does it isn't very
245 clean. The result may be that it gives up during its rehashing and
246 refuses to get/set something it could've, had it been done right.
247
249 This module is Copyright (c) 2003 Brad Fitzpatrick. All rights
250 reserved.
251 You may distribute under the terms of either the GNU General Public
253 License or the Artistic License, as specified in the Perl README file.
254
256 This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
257
259 See the memcached website:
260 http://www.danga.com/memcached/
261
263 Brad Fitzpatrick <brad@danga.com>
264 Anatoly Vorobey <mellon@pobox.com>
266 Brad Whitaker <whitaker@danga.com>
268 Jamie McCarthy <jamie@mccarthy.vg>
270perl v5.28.0 2012-05-19 Cache::Memcached(3)