File | /usr/local/lib/perl5/site_perl/5.10.1/darwin-2level/Memcached/libmemcached.pm |
Statements Executed | 21 |
Statement Execution Time | 1.07ms |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
24 | 1 | 2 | 5.18ms | 5.18ms | memcached_get (xsub) | Memcached::libmemcached::
17 | 1 | 2 | 4.16ms | 4.16ms | memcached_set (xsub) | Memcached::libmemcached::
3 | 1 | 2 | 1.63ms | 1.63ms | memcached_flush (xsub) | Memcached::libmemcached::
1 | 1 | 1 | 1.00ms | 1.13ms | BEGIN@21 | Memcached::libmemcached::
1 | 1 | 2 | 474µs | 474µs | DESTROY (xsub) | Memcached::libmemcached::
58 | 3 | 2 | 206µs | 206µs | errstr (xsub) | Memcached::libmemcached::
1 | 1 | 2 | 57µs | 57µs | memcached_create (xsub) | Memcached::libmemcached::
1 | 1 | 2 | 24µs | 24µs | memcached_server_add (xsub) | Memcached::libmemcached::
1 | 1 | 1 | 15µs | 27µs | BEGIN@3 | Memcached::libmemcached::
1 | 1 | 1 | 10µs | 47µs | BEGIN@18 | Memcached::libmemcached::
1 | 1 | 1 | 7µs | 45µs | BEGIN@19 | Memcached::libmemcached::
1 | 1 | 1 | 7µs | 10µs | BEGIN@4 | Memcached::libmemcached::
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 # 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 # 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 # 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 # 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 # 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 | |||||
# 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 | |||||
# 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 | |||||
# 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 | |||||
# 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 | |||||
# 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 | |||||
# 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 |