Profile of /usr/local/lib/perl5/site_perl/5.10.1/darwin-2level/Memcached/libmemcached.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For 05.Domain_and_Item.t
Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:23:05 2010

File | /usr/local/lib/perl5/site_perl/5.10.1/darwin-2level/Memcached/libmemcached.pm
Statements Executed | 21
Statement Execution Time | 1.07ms

Subroutines — ordered by exclusive time
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
24 | 1 | 2 | 5.18ms | 5.18ms | Memcached::libmemcached::::memcached_getMemcached::libmemcached::memcached_get (xsub)
17 | 1 | 2 | 4.16ms | 4.16ms | Memcached::libmemcached::::memcached_setMemcached::libmemcached::memcached_set (xsub)
3 | 1 | 2 | 1.63ms | 1.63ms | Memcached::libmemcached::::memcached_flushMemcached::libmemcached::memcached_flush (xsub)
1 | 1 | 1 | 1.00ms | 1.13ms | Memcached::libmemcached::::BEGIN@21Memcached::libmemcached::BEGIN@21
1 | 1 | 2 | 474µs | 474µs | Memcached::libmemcached::::DESTROYMemcached::libmemcached::DESTROY (xsub)
58 | 3 | 2 | 206µs | 206µs | Memcached::libmemcached::::errstrMemcached::libmemcached::errstr (xsub)
1 | 1 | 2 | 57µs | 57µs | Memcached::libmemcached::::memcached_createMemcached::libmemcached::memcached_create (xsub)
1 | 1 | 2 | 24µs | 24µs | Memcached::libmemcached::::memcached_server_addMemcached::libmemcached::memcached_server_add (xsub)
1 | 1 | 1 | 15µs | 27µs | Memcached::libmemcached::::BEGIN@3Memcached::libmemcached::BEGIN@3
1 | 1 | 1 | 10µs | 47µs | Memcached::libmemcached::::BEGIN@18Memcached::libmemcached::BEGIN@18
1 | 1 | 1 | 7µs | 45µs | Memcached::libmemcached::::BEGIN@19Memcached::libmemcached::BEGIN@19
1 | 1 | 1 | 7µs | 10µs | Memcached::libmemcached::::BEGIN@4Memcached::libmemcached::BEGIN@4

Call graph for these subroutines as a Graphviz dot language file.

Line | State ments | Time on line | Calls | Time in subs | Code
--- | --- | --- | --- | --- | ---
1 |  |  |  |  | package Memcached::libmemcached;
2 |  |  |  |  |
3 | 3 | 22µs | 2 | 39µs | # spent 27µs (15+12) within Memcached::libmemcached::BEGIN@3 which was called # once (15µs+12µs) by SimpleDB::Class::Cache::BEGIN@31 at line 3 use warnings; # spent 27µs making 1 call to Memcached::libmemcached::BEGIN@3 # spent 12µs making 1 call to warnings::import
4 | 3 | 30µs | 2 | 12µs | # spent 10µs (7+3) within Memcached::libmemcached::BEGIN@4 which was called # once (7µs+3µs) by SimpleDB::Class::Cache::BEGIN@31 at line 4 use strict; # spent 10µs making 1 call to Memcached::libmemcached::BEGIN@4 # spent 3µs making 1 call to strict::import
5 |  |  |  |  |
6 |  |  |  |  | =head1 NAME
7 |  |  |  |  |
8 |  |  |  |  | Memcached::libmemcached - Thin fast full interface to the libmemcached client API
9 |  |  |  |  |
10 |  |  |  |  | =head1 VERSION
11 |  |  |  |  |
12 |  |  |  |  | Version 0.3102 (with libmemcached-0.31 embedded)
13 |  |  |  |  |
14 |  |  |  |  | =cut
15 |  |  |  |  |
16 | 1 | 600ns |  |  | our $VERSION = '0.3102';
17 |  |  |  |  |
18 | 3 | 25µs | 2 | 84µs | # spent 47µs (10+37) within Memcached::libmemcached::BEGIN@18 which was called # once (10µs+37µs) by SimpleDB::Class::Cache::BEGIN@31 at line 18 use Carp; # spent 47µs making 1 call to Memcached::libmemcached::BEGIN@18 # spent 37µs making 1 call to Exporter::import
19 | 3 | 22µs | 2 | 84µs | # spent 45µs (7+38) within Memcached::libmemcached::BEGIN@19 which was called # once (7µs+38µs) by SimpleDB::Class::Cache::BEGIN@31 at line 19 use base qw(Exporter); # spent 45µs making 1 call to Memcached::libmemcached::BEGIN@19 # spent 38µs making 1 call to base::import
20 |  |  |  |  |
21 | 3 | 237µs | 2 | 1.17ms | # spent 1.13ms (1.00+129µs) within Memcached::libmemcached::BEGIN@21 which was called # once (1.00ms+129µs) by SimpleDB::Class::Cache::BEGIN@31 at line 21 use Memcached::libmemcached::API; # spent 1.13ms making 1 call to Memcached::libmemcached::BEGIN@21 # spent 37µs making 1 call to Exporter::import
22 | 1 | 82µs | 2 | 25µs | our @EXPORT_OK = ( # spent 15µs making 1 call to Memcached::libmemcached::API::libmemcached_constants # spent 10µs making 1 call to Memcached::libmemcached::API::libmemcached_functions
23 |  |  |  |  | libmemcached_functions(),
24 |  |  |  |  | libmemcached_constants(),
25 |  |  |  |  | );
26 | 1 | 3µs | 1 | 76µs | our %EXPORT_TAGS = libmemcached_tags(); # spent 76µs making 1 call to Memcached::libmemcached::API::libmemcached_tags
27 |  |  |  |  |
28 | 1 | 600ns |  |  | require XSLoader;
29 | 1 | 634µs | 1 | 623µs | XSLoader::load('Memcached::libmemcached', $VERSION); # spent 623µs making 1 call to XSLoader::load
30 |  |  |  |  |
31 |  |  |  |  | =head1 SYNOPSIS
32 |  |  |  |  |
33 |  |  |  |  | use Memcached::libmemcached;
34 |  |  |  |  |
35 |  |  |  |  | $memc = memcached_create();
36 |  |  |  |  |
37 |  |  |  |  | memcached_server_add($memc, "localhost");
38 |  |  |  |  |
39 |  |  |  |  | memcached_set($memc, $key, $value);
40 |  |  |  |  |
41 |  |  |  |  | $value = memcached_get($memc, $key);
42 |  |  |  |  |
43 |  |  |  |  | =head1 DESCRIPTION
44 |  |  |  |  |
45 |  |  |  |  | Memcached::libmemcached is a very thin, highly efficient, wrapper around the
46 |  |  |  |  | libmemcached library. It's implemented almost entirely in C.
47 |  |  |  |  |
48 |  |  |  |  | It gives full access to the rich functionality offered by libmemcached.
49 |  |  |  |  | libmemcached is fast, light on memory usage, thread safe, and provide full
50 |  |  |  |  | access to server side methods.
51 |  |  |  |  |
52 |  |  |  |  | - Synchronous and Asynchronous support.
53 |  |  |  |  | - TCP and Unix Socket protocols.
54 |  |  |  |  | - A half dozen or so different hash algorithms.
55 |  |  |  |  | - Implementations of the new cas, replace, and append operators.
56 |  |  |  |  | - Man pages written up on entire API.
57 |  |  |  |  | - Implements both modulo and consistent hashing solutions.
58 |  |  |  |  |
59 |  |  |  |  | (At the moment Memcached::libmemcached is very new and not all the functions in
60 |  |  |  |  | libmemcached have perl interfaces yet. We're focussing on the core
61 |  |  |  |  | infrastructure and the most common functions. It's usually trivial to add
62 |  |  |  |  | functions - just a few lines in libmemcached.xs, a few lines of documentation,
63 |  |  |  |  | and a few lines of testing. Volunteers welcome!)
64 |  |  |  |  |
65 |  |  |  |  | The libmemcached library documentation (which is bundled with this module)
66 |  |  |  |  | serves as the primary reference for the functionality.
67 |  |  |  |  |
68 |  |  |  |  | This documentation provides summary of the functions, along with any issues
69 |  |  |  |  | specific to this perl interface, and references to the documentation for the
70 |  |  |  |  | corresponding functions in the underlying library.
71 |  |  |  |  |
72 |  |  |  |  | For more information on libmemcached, see L<http://tangent.org/552/libmemcached.html>
73 |  |  |  |  |
74 |  |  |  |  | =head1 CONVENTIONS
75 |  |  |  |  |
76 |  |  |  |  | =head2 Terminology
77 |  |  |  |  |
78 |  |  |  |  | The term "memcache" is used to refer to the C<memcached_st> structure at the
79 |  |  |  |  | heart of the libmemcached library. We'll use $memc to represent this
80 |  |  |  |  | structure in perl code. (The libmemcached library documentation uses C<ptr>.)
81 |  |  |  |  |
82 |  |  |  |  | =head2 Traditional and Object-Oriented
83 |  |  |  |  |
84 |  |  |  |  | There are two ways to use the functionality offered by this module:
85 |  |  |  |  |
86 |  |  |  |  | B<*> You can import the functions you want to use and call them explicitly.
87 |  |  |  |  |
88 |  |  |  |  | B<*> Or, you can use $memc as an object and call most of the functions as methods.
89 |  |  |  |  | You can do that for any function that takes a $memc (ptr) as its first
90 |  |  |  |  | argument, which is almost all of them.
91 |  |  |  |  |
92 |  |  |  |  | Since the primary focus of this module is to be a thin wrapper around
93 |  |  |  |  | libmemcached, the bulk of this documentation describes the traditional
94 |  |  |  |  | functional interface.
95 |  |  |  |  |
96 |  |  |  |  | The object-oriented interface is mainly targeted at modules wishing to subclass
97 |  |  |  |  | Memcached::libmemcached, such as Cache::Memcached::libmemcached. For more information
98 |  |  |  |  | see L</OBJECT-ORIENTED INTERFACE>.
99 |  |  |  |  |
100 |  |  |  |  | =head2 Function Names and Arguments
101 |  |  |  |  |
102 |  |  |  |  | The function names in the libmemcached library have exactly the same names in
103 |  |  |  |  | Memcached::libmemcached.
104 |  |  |  |  |
105 |  |  |  |  | The function arguments are also the same as the libmemcached library and
106 |  |  |  |  | documentation, with two exceptions:
107 |  |  |  |  |
108 |  |  |  |  | B<*> There are no I<length> arguments. Wherever the libmemcached documentation
109 |  |  |  |  | shows a length argument (input or output) the corresponding argument doesn't
110 |  |  |  |  | exist in the Perl API because it's not needed.
111 |  |  |  |  |
112 |  |  |  |  | B<*> Some arguments are optional.
113 |  |  |  |  |
114 |  |  |  |  | Many libmemcached function arguments are I<output values>: the argument is the
115 |  |  |  |  | address of the value that the function will modify. For these the perl function
116 |  |  |  |  | will modify the argument directly if it can. For example, in this call:
117 |  |  |  |  |
118 |  |  |  |  | $value = memcached_get($memc, $key, $flags, $rc);
119 |  |  |  |  |
120 |  |  |  |  | The $flags and $rc arguments are output values that are modified by the
121 |  |  |  |  | memcached_get() function.
122 |  |  |  |  |
123 |  |  |  |  | See the L</Type Mapping> section for the fine detail of how each argument type
124 |  |  |  |  | is handled.
125 |  |  |  |  |
126 |  |  |  |  | =head2 Return Status
127 |  |  |  |  |
128 |  |  |  |  | Most of the functions return an integer status value. This is shown as
129 |  |  |  |  | C<memcached_return> in the libmemcached documentation.
130 |  |  |  |  |
131 |  |  |  |  | In the perl interface this value is I<not> returned directly. Instead a simple
132 |  |  |  |  | boolean is returned: true for 'success', defined but false for some
133 |  |  |  |  | 'unsuccessful' conditions like 'not found', and undef for all other cases (i.e., errors).
134 |  |  |  |  |
135 |  |  |  |  | All the functions documented below return this simple boolean value unless
136 |  |  |  |  | otherwise indicated.
137 |  |  |  |  |
138 |  |  |  |  | The actual C<memcached_return> integer value, and corresponding error message,
139 |  |  |  |  | for the last libmemcached function call can be accessed via the
140 |  |  |  |  | L</errstr> method.
141 |  |  |  |  |
142 |  |  |  |  | =head2 Unimplemented Functions
143 |  |  |  |  |
144 |  |  |  |  | Functions relating to managing lists of servers (memcached_server_push, and
145 |  |  |  |  | memcached_server_list) have not been implemenetd because they're not needed and
146 |  |  |  |  | likely to be deprecated by libmemcached.
147 |  |  |  |  |
148 |  |  |  |  | Functions relating to iterating through results (memcached_result_*) have not
149 |  |  |  |  | been implemented yet. They're not a priority because similar functionality is
150 |  |  |  |  | available via the callbacks. See L</set_callback_coderefs>.
151 |  |  |  |  |
152 |  |  |  |  | Functions relating to stats should be implemented soonish. Patches welcome!
153 |  |  |  |  |
154 |  |  |  |  | =cut
155 |  |  |  |  |
156 |  |  |  |  | =head1 EXPORTS
157 |  |  |  |  |
158 |  |  |  |  | All the public functions in libmemcached are available for import.
159 |  |  |  |  |
160 |  |  |  |  | All the public constants and enums in libmemcached are also available for import.
161 |  |  |  |  |
162 |  |  |  |  | Exporter tags are defined for each enum. This allows you to import groups of
163 |  |  |  |  | constants easily. For example, to enable consistent hashing you could use:
164 |  |  |  |  |
165 |  |  |  |  | use Memcached::libmemcached qw(:memcached_behavior :memcached_server_distribution);
166 |  |  |  |  |
167 |  |  |  |  | memcached_behavior_set($memc, MEMCACHED_BEHAVIOR_DISTRIBUTION(), MEMCACHED_DISTRIBUTION_CONSISTENT());
168 |  |  |  |  |
169 |  |  |  |  | The L<Exporter> module allows patterns in the import list, so to import all the
170 |  |  |  |  | functions, for example, you can use:
171 |  |  |  |  |
172 |  |  |  |  | use Memcached::libmemcached qw(/^memcached/);
173 |  |  |  |  |
174 |  |  |  |  | Refer to L<Memcached::libmemcached::constants> for a full list of the available
175 |  |  |  |  | constants and the tags they are grouped by.
176 |  |  |  |  |
177 |  |  |  |  | =head1 FUNCTIONS
178 |  |  |  |  |
179 |  |  |  |  | =head2 Functions For Managing Memcaches
180 |  |  |  |  |
181 |  |  |  |  | =head3 memcached_create
182 |  |  |  |  |
183 |  |  |  |  | my $memc = memcached_create();
184 |  |  |  |  |
185 |  |  |  |  | Creates and returns a 'memcache' that represents the state of
186 |  |  |  |  | communication with a set of memcached servers.
187 |  |  |  |  | See L<Memcached::libmemcached::memcached_create>.
188 |  |  |  |  |
189 |  |  |  |  | =head3 memcached_clone
190 |  |  |  |  |
191 |  |  |  |  | my $memc = memcached_clone(undef, undef);
192 |  |  |  |  |
193 |  |  |  |  | XXX Not currently recommended for use.
194 |  |  |  |  | See L<Memcached::libmemcached::memcached_create>.
195 |  |  |  |  |
196 |  |  |  |  | =head3 memcached_free
197 |  |  |  |  |
198 |  |  |  |  | memcached_free($memc);
199 |  |  |  |  |
200 |  |  |  |  | Frees the memory associated with $memc.
201 |  |  |  |  | After calling it $memc can't be used.
202 |  |  |  |  | See L<Memcached::libmemcached::memcached_create>.
203 |  |  |  |  |
204 |  |  |  |  | =head3 memcached_server_count
205 |  |  |  |  |
206 |  |  |  |  | $server_count= memcached_server_count($memc);
207 |  |  |  |  |
208 |  |  |  |  | Returns a count of the number of servers
209 |  |  |  |  | associated with $memc.
210 |  |  |  |  | See L<Memcached::libmemcached::memcached_servers>.
211 |  |  |  |  |
212 |  |  |  |  | =head3 memcached_server_add
213 |  |  |  |  |
214 |  |  |  |  | memcached_server_add($memc, $hostname, $port);
215 |  |  |  |  |
216 |  |  |  |  | Adds details of a single memcached server (accessed via TCP/IP) to $memc.
217 |  |  |  |  | See L<Memcached::libmemcached::memcached_servers>.
218 |  |  |  |  |
219 |  |  |  |  | =head3 memcached_server_add_unix_socket
220 |  |  |  |  |
221 |  |  |  |  | memcached_server_add_unix_socket($memc, $socket_path);
222 |  |  |  |  |
223 |  |  |  |  | Adds details of a single memcached server (accessed via a UNIX domain socket) to $memc.
224 |  |  |  |  | See L<Memcached::libmemcached::memcached_servers>.
225 |  |  |  |  |
226 |  |  |  |  | =head3 memcached_behavior_set
227 |  |  |  |  |
228 |  |  |  |  | memcached_behavior_set($memc, $option_key, $option_value);
229 |  |  |  |  |
230 |  |  |  |  | Changes the value of a particular option.
231 |  |  |  |  | See L<Memcached::libmemcached::memcached_behavior>.
232 |  |  |  |  |
233 |  |  |  |  | =head3 memcached_behavior_get
234 |  |  |  |  |
235 |  |  |  |  | memcached_behavior_get($memc, $option_key);
236 |  |  |  |  |
237 |  |  |  |  | Get the value of a particular option.
238 |  |  |  |  | See L<Memcached::libmemcached::memcached_behavior>.
239 |  |  |  |  |
240 |  |  |  |  | =cut
241 |  |  |  |  |
242 |  |  |  |  |
243 |  |  |  |  | =head2 Functions for Setting Values
244 |  |  |  |  |
245 |  |  |  |  | See L<Memcached::libmemcached::memcached_set>.
246 |  |  |  |  |
247 |  |  |  |  | =head3 memcached_set
248 |  |  |  |  |
249 |  |  |  |  | memcached_set($memc, $key, $value);
250 |  |  |  |  | memcached_set($memc, $key, $value, $expiration, $flags);
251 |  |  |  |  |
252 |  |  |  |  | Set $value as the value of $key.
253 |  |  |  |  | $expiration and $flags are both optional and default to 0.
254 |  |  |  |  |
255 |  |  |  |  | =head3 memcached_add
256 |  |  |  |  |
257 |  |  |  |  | memcached_add($memc, $key, $value);
258 |  |  |  |  | memcached_add($memc, $key, $value, $expiration, $flags);
259 |  |  |  |  |
260 |  |  |  |  | Like L</memcached_set> except that an error is returned if $key I<is> already
261 |  |  |  |  | stored in the server.
262 |  |  |  |  |
263 |  |  |  |  | =head3 memcached_replace
264 |  |  |  |  |
265 |  |  |  |  | memcached_replace($memc, $key, $value);
266 |  |  |  |  | memcached_replace($memc, $key, $value, $expiration, $flags);
267 |  |  |  |  |
268 |  |  |  |  | Like L</memcached_set> except that an error is returned if $key I<is not> already
269 |  |  |  |  | error is returned.
270 |  |  |  |  |
271 |  |  |  |  | =head3 memcached_prepend
272 |  |  |  |  |
273 |  |  |  |  | memcached_prepend($memc, $key, $value);
274 |  |  |  |  | memcached_prepend($memc, $key, $value, $expiration, $flags);
275 |  |  |  |  |
276 |  |  |  |  | Prepend $value to the value of $key. $key must already exist.
277 |  |  |  |  | $expiration and $flags are both optional and default to 0.
278 |  |  |  |  |
279 |  |  |  |  | =head3 memcached_append
280 |  |  |  |  |
281 |  |  |  |  | memcached_append($memc, $key, $value);
282 |  |  |  |  | memcached_append($memc, $key, $value, $expiration, $flags);
283 |  |  |  |  |
284 |  |  |  |  | Append $value to the value of $key. $key must already exist.
285 |  |  |  |  | $expiration and $flags are both optional and default to 0.
286 |  |  |  |  |
287 |  |  |  |  | =head3 memcached_cas
288 |  |  |  |  |
289 |  |  |  |  | memcached_cas($memc, $key, $value, $expiration, $flags, $cas)
290 |  |  |  |  |
291 |  |  |  |  | Overwrites data in the server stored as $key as long as $cas
292 |  |  |  |  | still has the same value in the server.
293 |  |  |  |  |
294 |  |  |  |  | Cas is still buggy in memached. Turning on support for it in libmemcached is
295 |  |  |  |  | optional. Please see memcached_behavior_set() for information on how to do this.
296 |  |  |  |  |
297 |  |  |  |  | XXX and the memcached_result_cas() function isn't implemented yet
298 |  |  |  |  | so you can't get the $cas to use.
299 |  |  |  |  |
300 |  |  |  |  | =cut
301 |  |  |  |  |
302 |  |  |  |  | =head2 Functions for Fetching Values
303 |  |  |  |  |
304 |  |  |  |  | See L<Memcached::libmemcached::memcached_get>.
305 |  |  |  |  |
306 |  |  |  |  | The memcached_fetch_result() and
307 |  |  |  |  |
308 |  |  |  |  | =head3 memcached_get
309 |  |  |  |  |
310 |  |  |  |  | $value = memcached_get($memc, $key);
311 |  |  |  |  | $value = memcached_get($memc, $key, $flags, $rc);
312 |  |  |  |  |
313 |  |  |  |  | Get and return the value of $key. Returns undef on error.
314 |  |  |  |  |
315 |  |  |  |  | Also updates $flags to the value of the flags stored with $value,
316 |  |  |  |  | and updates $rc with the return code.
317 |  |  |  |  |
318 |  |  |  |  |
319 |  |  |  |  | =head3 memcached_mget
320 |  |  |  |  |
321 |  |  |  |  | memcached_mget($memc, \@keys);
322 |  |  |  |  | memcached_mget($memc, \%keys);
323 |  |  |  |  |
324 |  |  |  |  | Triggers the asynchronous fetching of multiple keys at once. For multiple key
325 |  |  |  |  | operations it is always faster to use this function. You I<must> then use
326 |  |  |  |  | memcached_fetch() or memcached_fetch_result() to retrieve any keys found.
327 |  |  |  |  | No error is given on keys that are not found.
328 |  |  |  |  |
329 |  |  |  |  | Instead of this function, you'd normally use the L</mget_into_hashref> method.
330 |  |  |  |  |
331 |  |  |  |  | =head3 memcached_fetch
332 |  |  |  |  |
333 |  |  |  |  | $value = memcached_fetch($memc, $key);
334 |  |  |  |  | $value = memcached_fetch($memc, $key, $flag, $rc);
335 |  |  |  |  |
336 |  |  |  |  | Fetch the next $key and $value pair returned in response to a memcached_mget() call.
337 |  |  |  |  | Returns undef if there are no more values.
338 |  |  |  |  |
339 |  |  |  |  | If $flag is given then it will be updated to whatever flags were stored with the value.
340 |  |  |  |  | If $rc is given then it will be updated to the return code.
341 |  |  |  |  |
342 |  |  |  |  | This is similar to L</memcached_get> except its fetching the results from the previous
343 |  |  |  |  | call to L</memcached_mget> and $key is an output parameter instead of an input.
344 |  |  |  |  | Usually you'd just use the L</mget_into_hashref> method instead.
345 |  |  |  |  |
346 |  |  |  |  | =cut
347 |  |  |  |  |
348 |  |  |  |  |
349 |  |  |  |  | =head2 Functions for Incrementing and Decrementing Values
350 |  |  |  |  |
351 |  |  |  |  | =head3 memcached_increment
352 |  |  |  |  |
353 |  |  |  |  | memcached_increment( $key, $offset, $new_value_out );
354 |  |  |  |  |
355 |  |  |  |  | Increments the integer value associated with $key by $offset and returns the new value in $new_value_out.
356 |  |  |  |  | See also L<Memcached::libmemcached::memcached_auto>.
357 |  |  |  |  |
358 |  |  |  |  | =head3 memcached_decrement
359 |  |  |  |  |
360 |  |  |  |  | memcached_decrement( $key, $offset, $new_value_out );
361 |  |  |  |  |
362 |  |  |  |  | Decrements the integer value associated with $key by $offset and returns the new value in $new_value_out.
363 |  |  |  |  | See also L<Memcached::libmemcached::memcached_auto>.
364 |  |  |  |  |
365 |  |  |  |  | =cut
366 |  |  |  |  |
367 |  |  |  |  |
368 |  |  |  |  | =head2 Functions for Deleting Values from memcached
369 |  |  |  |  |
370 |  |  |  |  | See L<Memcached::libmemcached::memcached_delete>.
371 |  |  |  |  |
372 |  |  |  |  | =head3 memcached_delete
373 |  |  |  |  |
374 |  |  |  |  | memcached_delete($memc, $key);
375 |  |  |  |  | memcached_delete($memc, $key, $expiration);
376 |  |  |  |  |
377 |  |  |  |  | Delete $key. If $expiration is greater than zero then the key is deleted by
378 |  |  |  |  | memcached after that many seconds.
379 |  |  |  |  |
380 |  |  |  |  | =cut
381 |  |  |  |  |
382 |  |  |  |  |
383 |  |  |  |  | =head2 Functions for Accessing Statistics from memcached
384 |  |  |  |  |
385 |  |  |  |  | Not yet implemented.
386 |  |  |  |  |
387 |  |  |  |  | See L<Memcached::libmemcached::memcached_stats>.
388 |  |  |  |  |
389 |  |  |  |  | =cut
390 |  |  |  |  |
391 |  |  |  |  |
392 |  |  |  |  | =head2 Miscellaneous Functions
393 |  |  |  |  |
394 |  |  |  |  | =head2 memcached_lib_version
395 |  |  |  |  |
396 |  |  |  |  | $version = memcached_lib_version()
397 |  |  |  |  |
398 |  |  |  |  | Returns a simple version string, like "0.15", representing the libmemcached
399 |  |  |  |  | version (version of the client library, not server).
400 |  |  |  |  |
401 |  |  |  |  | =head2 memcached_version
402 |  |  |  |  |
403 |  |  |  |  | $version = memcached_version($memc)
404 |  |  |  |  | ($version1, $version2, $version3) = memcached_version($memc)
405 |  |  |  |  |
406 |  |  |  |  | Returns the version of all memcached servers to respond to the version request.
407 |  |  |  |  |
408 |  |  |  |  | In scalar context returns a simple version string, like "1.2.3".
409 |  |  |  |  | In list context returns the individual version component numbers.
410 |  |  |  |  | Returns an empty list if there was an error.
411 |  |  |  |  |
412 |  |  |  |  | Note that the return value differs from that of the underlying libmemcached
413 |  |  |  |  | library memcached_version() function.
414 |  |  |  |  |
415 |  |  |  |  | =head2 memcached_verbosity
416 |  |  |  |  |
417 |  |  |  |  | memcached_verbosity($memc, $verbosity)
418 |  |  |  |  |
419 |  |  |  |  | Modifies the "verbosity" of the memcached servers associated with $memc.
420 |  |  |  |  | See L<Memcached::libmemcached::memcached_verbosity>.
421 |  |  |  |  |
422 |  |  |  |  | =head3 memcached_flush
423 |  |  |  |  |
424 |  |  |  |  | memcached_flush($memc, $expiration);
425 |  |  |  |  |
426 |  |  |  |  | Wipe clean the contents of associated memcached servers.
427 |  |  |  |  | See L<Memcached::libmemcached::memcached_flush>.
428 |  |  |  |  |
429 |  |  |  |  | =head2 memcached_quit
430 |  |  |  |  |
431 |  |  |  |  | memcached_quit($memc)
432 |  |  |  |  |
433 |  |  |  |  | Disconnect from all currently connected servers and reset libmemcached state associated with $memc.
434 |  |  |  |  | Not normally called explicitly.
435 |  |  |  |  | See L<Memcached::libmemcached::memcached_quit>.
436 |  |  |  |  |
437 |  |  |  |  | =head3 memcached_strerror
438 |  |  |  |  |
439 |  |  |  |  | $string = memcached_strerror($memc, $return_code)
440 |  |  |  |  |
441 |  |  |  |  | memcached_strerror() takes a C<memcached_return> value and returns a string describing the error.
442 |  |  |  |  | The string should be treated as read-only (it may be so in future versions).
443 |  |  |  |  | See also L<Memcached::libmemcached::memcached_strerror>.
444 |  |  |  |  |
445 |  |  |  |  | This function is rarely needed in the Perl interface because the return code is
446 |  |  |  |  | a I<dualvar> that already contains the error string.
447 |  |  |  |  |
448 |  |  |  |  | =cut
449 |  |  |  |  |
450 |  |  |  |  | =head2 Unsupported Functions
451 |  |  |  |  |
452 |  |  |  |  | =head3 (stats)
453 |  |  |  |  | =cut
454 |  |  |  |  |
455 |  |  |  |  | =head2 Grouping Keys On Servers
456 |  |  |  |  |
457 |  |  |  |  | Normally libmemcached hashes the $key value to select which memcached server to
458 |  |  |  |  | communicate with. If you have several keys relating to a single object then
459 |  |  |  |  | it's very likely that the corresponding values will be stored in different
460 |  |  |  |  | memcached servers.
461 |  |  |  |  |
462 |  |  |  |  | It would be more efficient, in general, when setting and getting multiple
463 |  |  |  |  | related values, if it was possible to specify a different value to be hashed to
464 |  |  |  |  | select which memcached server to communicate with. With libmemcached, you can.
465 |  |  |  |  |
466 |  |  |  |  | Most of the functions for setting and getting values have C<*_by_key> variants
467 |  |  |  |  | for exactly this reason. These all have an extra $master_key parameter
468 |  |  |  |  | immediately after the $memc parameter. For example:
469 |  |  |  |  |
470 |  |  |  |  | memcached_mget($memc, \%keys, \%dest);
471 |  |  |  |  |
472 |  |  |  |  | memcached_mget_by_key($memc, $maskey_key, \%keys, \%dest);
473 |  |  |  |  |
474 |  |  |  |  | The C<*_by_key> variants all work in exactly the same way as the corresponding
475 |  |  |  |  | plain function, except that libmemcached hashes $master_key instead of $key to
476 |  |  |  |  | which memcached server to communicate with.
477 |  |  |  |  |
478 |  |  |  |  | If $master_key is undef then the functions behave the same as their non-by-key
479 |  |  |  |  | variants, i.e., $key is used for hashing.
480 |  |  |  |  |
481 |  |  |  |  | By-key variants of L</Functions for Fetching Values>:
482 |  |  |  |  |
483 |  |  |  |  | =head3 memcached_get_by_key
484 |  |  |  |  |
485 |  |  |  |  | =head3 memcached_mget_by_key
486 |  |  |  |  |
487 |  |  |  |  | By-key variants of L</Functions for Setting Values>:
488 |  |  |  |  |
489 |  |  |  |  | =head3 memcached_set_by_key
490 |  |  |  |  |
491 |  |  |  |  | =head3 memcached_replace_by_key
492 |  |  |  |  |
493 |  |  |  |  | =head3 memcached_add_by_key
494 |  |  |  |  |
495 |  |  |  |  | =head3 memcached_append_by_key
496 |  |  |  |  |
497 |  |  |  |  | =head3 memcached_cas_by_key
498 |  |  |  |  |
499 |  |  |  |  | =head3 memcached_prepend_by_key
500 |  |  |  |  |
501 |  |  |  |  | =head3 memcached_delete_by_key
502 |  |  |  |  |
503 |  |  |  |  | =head1 OBJECT-ORIENTED INTERFACE
504 |  |  |  |  |
505 |  |  |  |  | =head2 Methods
506 |  |  |  |  |
507 |  |  |  |  | =head3 new
508 |  |  |  |  |
509 |  |  |  |  | $memc = $class->new; # same as memcached_create()
510 |  |  |  |  |
511 |  |  |  |  | =head3 errstr
512 |  |  |  |  |
513 |  |  |  |  | $errstr = $memc->errstr;
514 |  |  |  |  |
515 |  |  |  |  | Returns the error message and code from the most recent call to any
516 |  |  |  |  | libmemcached function that returns a C<memcached_return>, which most do.
517 |  |  |  |  |
518 |  |  |  |  | The return value is a I<dualvar>, like $!, which means it has separate numeric
519 |  |  |  |  | and string values. The numeric value is the memcached_return integer value,
520 |  |  |  |  | and the string value is the corresponding error message what memcached_strerror()
521 |  |  |  |  | would return.
522 |  |  |  |  |
523 |  |  |  |  | As a special case, if the memcached_return is MEMCACHED_ERRNO, indicating a
524 |  |  |  |  | system call error, then the string returned by strerror() is appended.
525 |  |  |  |  |
526 |  |  |  |  | This method is also currently callable as memcached_errstr() for compatibility
527 |  |  |  |  | with an earlier version, but that deprecated alias will start warning and then
528 |  |  |  |  | cease to exist in future versions.
529 |  |  |  |  |
530 |  |  |  |  | =head3 mget_into_hashref
531 |  |  |  |  |
532 |  |  |  |  | $memc->mget_into_hashref( \@keys, \%dest_hash); # keys from array
533 |  |  |  |  | $memc->mget_into_hashref( \%keys, \%dest_hash); # keys from hash
534 |  |  |  |  |
535 |  |  |  |  | Combines memcached_mget() and a memcached_fetch() loop into a single highly
536 |  |  |  |  | efficient call.
537 |  |  |  |  |
538 |  |  |  |  | Fetched values are stored in \%dest_hash, updating existing values or adding
539 |  |  |  |  | new ones as appropriate.
540 |  |  |  |  |
541 |  |  |  |  | This method is also currently callable as memcached_mget_into_hashref() for
542 |  |  |  |  | compatibility with an earlier version, but that deprecated alias will start
543 |  |  |  |  | warning and then cease to exist in future versions.
544 |  |  |  |  |
545 |  |  |  |  | =head3 get_multi
546 |  |  |  |  |
547 |  |  |  |  | $hash_ref = $memc->get_multi( @keys );
548 |  |  |  |  |
549 |  |  |  |  | Effectively the same as:
550 |  |  |  |  |
551 |  |  |  |  | $memc->mget_into_hashref( \@keys, $hash_ref = { } )
552 |  |  |  |  |
553 |  |  |  |  | So it's very similar to L</mget_into_hashref> but less efficient for large
554 |  |  |  |  | numbers of keys (because the keys have to be pushed onto the argument stack)
555 |  |  |  |  | and less flexible (because you can't add/update elements into an existing hash).
556 |  |  |  |  |
557 |  |  |  |  | This method is provided to optimize subclasses that want to provide a
558 |  |  |  |  | Cache::Memcached compatible API with maximum efficiency.
559 |  |  |  |  | Note, however, that C<get_multi> does I<not> support the L<Cache::Memcached>
560 |  |  |  |  | feature where a key can be a reference to an array [ $master_key, $key ].
561 |  |  |  |  | Use L</memcached_mget_by_key> directly if you need that feature.
562 |  |  |  |  |
563 |  |  |  |  | =head3 get
564 |  |  |  |  |
565 |  |  |  |  | $value = $memc->get( $key );
566 |  |  |  |  |
567 |  |  |  |  | Effectively the same as:
568 |  |  |  |  |
569 |  |  |  |  | $value = memcached_get( $memc, $key );
570 |  |  |  |  |
571 |  |  |  |  | The C<get> method also supports the L<Cache::Memcached> feature where $key can
572 |  |  |  |  | be a reference to an array [ $master_key, $key ]. In which case the call is
573 |  |  |  |  | effectively the same as:
574 |  |  |  |  |
575 |  |  |  |  | $value = memcached_get_by_key( $memc, $key->[0], $key->[1] )
576 |  |  |  |  |
577 |  |  |  |  |
578 |  |  |  |  | =head3 set_callback_coderefs
579 |  |  |  |  |
580 |  |  |  |  | $memc->set_callback_coderefs(\&set_callback, \&get_callback);
581 |  |  |  |  |
582 |  |  |  |  | This interface is I<experimental> and I<likely to change>. (It's also currently
583 |  |  |  |  | used by Cache::Memcached::libmemcached, so don't use it if you're using that module.)
584 |  |  |  |  |
585 |  |  |  |  | Specify functions which will be executed when values are set and/or get using $memc.
586 |  |  |  |  |
587 |  |  |  |  | When the callbacks are executed $_ is the value and the arguments are the key
588 |  |  |  |  | and flags value. Both $_ and the flags may be modified.
589 |  |  |  |  |
590 |  |  |  |  | Currently the functions must return an empty list.
591 |  |  |  |  |
592 |  |  |  |  | This method is also currently callable as memcached_set_callback_coderefs() for
593 |  |  |  |  | compatibility with an earlier version, but that deprecated alias will start
594 |  |  |  |  | warning and then cease to exist in future versions.
595 |  |  |  |  |
596 |  |  |  |  | =head3 walk_stats
597 |  |  |  |  |
598 |  |  |  |  | $memc->walk_stats( $stats_args, \&my_stats_callback );
599 |  |  |  |  |
600 |  |  |  |  | This interface is I<experimental> and I<likely to change>.
601 |  |  |  |  |
602 |  |  |  |  | Calls the memcached_stat() function to issue a "STAT $stats_args" command to
603 |  |  |  |  | the connected memcached servers. The $stats_args argument is usually an empty string.
604 |  |  |  |  |
605 |  |  |  |  | The callback function is called for each return value from each server.
606 |  |  |  |  | The callback will be passed 4 parameters:
607 |  |  |  |  |
608 |  |  |  |  | sub my_stats_callback {
609 |  |  |  |  | my ($key, $value, $hostport, $stats_args) = @_;
610 |  |  |  |  | # Do what you like with the above!
611 |  |  |  |  | return;
612 |  |  |  |  | }
613 |  |  |  |  |
614 |  |  |  |  | Currently the callback I<must> return an empty list.
615 |  |  |  |  |
616 |  |  |  |  | =head1 EXTRA INFORMATION
617 |  |  |  |  |
618 |  |  |  |  | =head2 Tracing Execution
619 |  |  |  |  |
620 |  |  |  |  | The C<PERL_LIBMEMCACHED_TRACE> environment variable can be used to control
621 |  |  |  |  | tracing. The value is read when L<memcached_create> is called.
622 |  |  |  |  |
623 |  |  |  |  | If set >= 1 then any non-success memcached_return value will be logged via warn().
624 |  |  |  |  |
625 |  |  |  |  | If set >= 2 or more then some data types will list conversions of input and output values for function calls.
626 |  |  |  |  |
627 |  |  |  |  | More flexible mechanisms will be added later.
628 |  |  |  |  |
629 |  |  |  |  | =head2 Type Mapping
630 |  |  |  |  |
631 |  |  |  |  | For pointer arguments, undef is mapped to null on input and null is mapped to
632 |  |  |  |  | undef on output.
633 |  |  |  |  |
634 |  |  |  |  | XXX expand with details from typemap file
635 |  |  |  |  |
636 |  |  |  |  | =head2 Deprecated Functions
637 |  |  |  |  |
638 |  |  |  |  | The following functions are available but deprecated in this release.
639 |  |  |  |  | In the next release they'll generate warnings.
640 |  |  |  |  | In a future release they'll be removed.
641 |  |  |  |  |
642 |  |  |  |  | =head3 memcached_errstr
643 |  |  |  |  |
644 |  |  |  |  | Use L</errstr> instead.
645 |  |  |  |  |
646 |  |  |  |  | =head3 memcached_mget_into_hashref
647 |  |  |  |  |
648 |  |  |  |  | Use L</mget_into_hashref> instead.
649 |  |  |  |  |
650 |  |  |  |  | =head3 memcached_set_callback_coderefs
651 |  |  |  |  |
652 |  |  |  |  | Use L</set_callback_coderefs> instead.
653 |  |  |  |  |
654 |  |  |  |  | =head1 AUTHOR EMERITUS
655 |  |  |  |  |
656 |  |  |  |  | Tim Bunce, C<< <Tim.Bunce@pobox.com> >> with help from Patrick Galbraith and Daisuke Maki.
657 |  |  |  |  |
658 |  |  |  |  | L<http://www.tim.bunce.name>
659 |  |  |  |  |
660 |  |  |  |  | =head1 CURRENT MAINTAINER
661 |  |  |  |  |
662 |  |  |  |  | Daisuke Maki C<< <daisuke@endeworks.jp> >>
663 |  |  |  |  |
664 |  |  |  |  | =head1 ACKNOWLEDGEMENTS
665 |  |  |  |  |
666 |  |  |  |  | Larry Wall for Perl, Brad Fitzpatrick for memcached, Brian Aker for libmemcached,
667 |  |  |  |  | and Patrick Galbraith and Daisuke Maki for helping with the implementation.
668 |  |  |  |  |
669 |  |  |  |  | =head1 PORTABILITY
670 |  |  |  |  |
671 |  |  |  |  | See Slaven Rezic's excellent CPAN Testers Matrix at L<http://bbbike.radzeit.de/~slaven/cpantestersmatrix.cgi?dist=Memcached-libmemcached>
672 |  |  |  |  |
673 |  |  |  |  | Along with Dave Cantrell's excellent CPAN Dependency tracker at
674 |  |  |  |  | L<http://cpandeps.cantrell.org.uk/?module=Memcached%3A%3Alibmemcached&perl=any+version&os=any+OS>
675 |  |  |  |  |
676 |  |  |  |  | =head1 BUGS
677 |  |  |  |  |
678 |  |  |  |  | Please report any bugs or feature requests to
679 |  |  |  |  | C<bug-memcached-libmemcached@rt.cpan.org>, or through the web interface at
680 |  |  |  |  | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Memcached-libmemcached>.
681 |  |  |  |  | I will be notified, and then you'll automatically be notified of progress on
682 |  |  |  |  | your bug as I make changes.
683 |  |  |  |  |
684 |  |  |  |  | =head1 CONTRIBUTING
685 |  |  |  |  |
686 |  |  |  |  | The source is hosted at L<http://perl-libmemcached.googlecode.com/>
687 |  |  |  |  | Patches and volunteers always welcome.
688 |  |  |  |  |
689 |  |  |  |  | =head1 COPYRIGHT & LICENSE
690 |  |  |  |  |
691 |  |  |  |  | Copyright 2008 Tim Bunce, All Rights Reserved.
692 |  |  |  |  |
693 |  |  |  |  | This program is free software; you can redistribute it and/or modify it
694 |  |  |  |  | under the same terms as Perl itself.
695 |  |  |  |  |
696 |  |  |  |  | =cut
697 |  |  |  |  |
698 | 1 | 11µs |  |  | 1; # End of Memcached::libmemcached
|  |  |  |  | # spent 474µs within Memcached::libmemcached::DESTROY which was called # once (474µs+0s) by main::NULL at line 0 of 05.Domain_and_Item.t sub Memcached::libmemcached::DESTROY; # xsub
|  |  |  |  | # spent 206µs within Memcached::libmemcached::errstr which was called 58 times, avg 4µs/call: # 29 times (97µs+0s) by SimpleDB::Class::Cache::get at line 259 of ../lib/SimpleDB/Class/Cache.pm, avg 3µs/call # 17 times (76µs+0s) by SimpleDB::Class::Cache::set at line 385 of ../lib/SimpleDB/Class/Cache.pm, avg 4µs/call # 12 times (34µs+0s) by SimpleDB::Class::Cache::flush at line 208 of ../lib/SimpleDB/Class/Cache.pm, avg 3µs/call sub Memcached::libmemcached::errstr; # xsub
|  |  |  |  | # spent 57µs within Memcached::libmemcached::memcached_create which was called # once (57µs+0s) by SimpleDB::Class::Cache::__ANON__[../lib/SimpleDB/Class/Cache.pm:106] at line 96 of ../lib/SimpleDB/Class/Cache.pm sub Memcached::libmemcached::memcached_create; # xsub
|  |  |  |  | # spent 1.63ms within Memcached::libmemcached::memcached_flush which was called 3 times, avg 542µs/call: # 3 times (1.63ms+0s) by SimpleDB::Class::Cache::flush at line 207 of ../lib/SimpleDB/Class/Cache.pm, avg 542µs/call sub Memcached::libmemcached::memcached_flush; # xsub
|  |  |  |  | # spent 5.18ms within Memcached::libmemcached::memcached_get which was called 24 times, avg 216µs/call: # 24 times (5.18ms+0s) by SimpleDB::Class::Cache::get at line 257 of ../lib/SimpleDB/Class/Cache.pm, avg 216µs/call sub Memcached::libmemcached::memcached_get; # xsub
|  |  |  |  | # spent 24µs within Memcached::libmemcached::memcached_server_add which was called # once (24µs+0s) by SimpleDB::Class::Cache::__ANON__[../lib/SimpleDB/Class/Cache.pm:106] at line 102 of ../lib/SimpleDB/Class/Cache.pm sub Memcached::libmemcached::memcached_server_add; # xsub
|  |  |  |  | # spent 4.16ms within Memcached::libmemcached::memcached_set which was called 17 times, avg 245µs/call: # 17 times (4.16ms+0s) by SimpleDB::Class::Cache::set at line 384 of ../lib/SimpleDB/Class/Cache.pm, avg 245µs/call sub Memcached::libmemcached::memcached_set; # xsub