| 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::libmemcached::memcached_get (xsub) |
| 17 | 1 | 2 | 4.16ms | 4.16ms | Memcached::libmemcached::memcached_set (xsub) |
| 3 | 1 | 2 | 1.63ms | 1.63ms | Memcached::libmemcached::memcached_flush (xsub) |
| 1 | 1 | 1 | 1.00ms | 1.13ms | Memcached::libmemcached::BEGIN@21 |
| 1 | 1 | 2 | 474µs | 474µs | Memcached::libmemcached::DESTROY (xsub) |
| 58 | 3 | 2 | 206µs | 206µs | Memcached::libmemcached::errstr (xsub) |
| 1 | 1 | 2 | 57µs | 57µs | Memcached::libmemcached::memcached_create (xsub) |
| 1 | 1 | 2 | 24µs | 24µs | Memcached::libmemcached::memcached_server_add (xsub) |
| 1 | 1 | 1 | 15µs | 27µs | Memcached::libmemcached::BEGIN@3 |
| 1 | 1 | 1 | 10µs | 47µs | Memcached::libmemcached::BEGIN@18 |
| 1 | 1 | 1 | 7µs | 45µs | Memcached::libmemcached::BEGIN@19 |
| 1 | 1 | 1 | 7µs | 10µs | Memcached::libmemcached::BEGIN@4 |
| 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 |