1Cache::Memcached(3)   User Contributed Perl Documentation  Cache::Memcached(3)
2
3
4

NAME

6       Cache::Memcached - client library for memcached (memory cache daemon)
7

SYNOPSIS

9         use Cache::Memcached;
10
11         $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
21         $memd->set("my_key", "Some value");
22         $memd->set("object_key", { 'complex' => [ "object", 2, 4 ]});
23
24         $val = $memd->get("my_key");
25         $val = $memd->get("object_key");
26         if ($val) { print $val->{'complex'}->[2]; }
27
28         $memd->incr("key");
29         $memd->decr("key");
30         $memd->incr("key", 2);
31

DESCRIPTION

33       This is the Perl API for memcached, a distributed memory cache daemon.
34       More information is available at:
35
36         http://www.danga.com/memcached/
37

CONSTRUCTOR

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
49           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
53           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
57           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
61           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
66           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
70           The other useful key is "debug", which when set to true will
71           produce diagnostics on STDERR.
72

METHODS

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
79       "set_debug"
80           Sets the "debug" flag.  See "new" constructor for more information.
81
82       "set_readonly"
83           Sets the "readonly" flag.  See "new" constructor for more
84           information.
85
86       "set_norehash"
87           Sets the "no_rehash" flag.  See "new" constructor for more
88           information.
89
90       "set_compress_threshold"
91           Sets the compression threshold. See "new" constructor for more
92           information.
93
94       "set_connect_timeout"
95           Sets the connect timeout. See "new" constructor for more
96           information.
97
98       "set_select_timeout"
99           Sets the select timeout. See "new" constructor for more
100           information.
101
102       "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
107       "get"
108           my $val = $memd->get($key);
109
110           Retrieves a key from the memcache.  Returns the value
111           (automatically thawed with Storable, if necessary) or undef.
112
113           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
119       "get_multi"
120           my $hashref = $memd->get_multi(@keys);
121
122           Retrieves multiple keys from the memcache doing just one query.
123           Returns a hashref of key/value pairs that were available.
124
125           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
130       "set"
131           $memd->set($key, $value[, $exptime]);
132
133           Unconditionally sets a key to a given value in the memcache.
134           Returns true if it was stored successfully.
135
136           The $key can optionally be an arrayref, with the first element
137           being the hash value, as described above.
138
139           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
145       "add"
146           $memd->add($key, $value[, $exptime]);
147
148           Like "set", but only stores in memcache if the key doesn't already
149           exist.
150
151       "replace"
152           $memd->replace($key, $value[, $exptime]);
153
154           Like "set", but only stores in memcache if the key already exists.
155           The opposite of "add".
156
157       "delete"
158           $memd->delete($key[, $time]);
159
160           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
166           You may also use the alternate method name remove, so
167           Cache::Memcached looks like the Cache::Cache API.
168
169       "incr"
170           $memd->incr($key[, $value]);
171
172           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
179       "decr"
180           $memd->decr($key[, $value]);
181
182           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
186       "stats"
187           $memd->stats([$keys]);
188
189           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
197           "misc"
198               The stats returned by a 'stats' command:  pid, uptime, version,
199               bytes, get_hits, etc.
200
201           "malloc"
202               The stats returned by a 'stats malloc':  total_alloc,
203               arena_size, etc.
204
205           "sizes"
206               The stats returned by a 'stats sizes'.
207
208           "self"
209               The stats for the $memd object itself (a copy of
210               $memd->{'stats'}).
211
212           "maps"
213               The stats returned by a 'stats maps'.
214
215           "cachedump"
216               The stats returned by a 'stats cachedump'.
217
218           "slabs"
219               The stats returned by a 'stats slabs'.
220
221           "items"
222               The stats returned by a 'stats items'.
223
224       "disconnect_all"
225           $memd->disconnect_all;
226
227           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
233       "flush_all"
234           $memd->flush_all;
235
236           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

BUGS

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
252       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

WARRANTY

256       This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
257

FAQ

259       See the memcached website:
260          http://www.danga.com/memcached/
261

AUTHORS

263       Brad Fitzpatrick <brad@danga.com>
264
265       Anatoly Vorobey <mellon@pobox.com>
266
267       Brad Whitaker <whitaker@danga.com>
268
269       Jamie McCarthy <jamie@mccarthy.vg>
270
271
272
273perl v5.32.1                      2021-01-26               Cache::Memcached(3)
Impressum