{ "content": [ { "type": "text", "text": "# Cache::Entry (perldoc)\n\n## NAME\n\nCache::Entry - interface for a cache entry\n\n## SYNOPSIS\n\nmy Cache::Entry $entry = $cache->entry( $key )\nmy $data;\nif ($entry->exists()) {\n$data = $entry->get();\n}\nelse {\n$data = getsomedata($key);\n$entry->set($data, '10 minutes');\n}\n\n## DESCRIPTION\n\nObjects derived from Cache::Entry represent an entry in a Cache. Methods are provided that act\nupon the data in the entry, and allow you to set things like the expiry time.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **STORING VALIDITY OBJECTS**\n- **STORING COMPLEX OBJECTS**\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Cache::Entry", "section": "", "mode": "perldoc", "summary": "Cache::Entry - interface for a cache entry", "synopsis": "my Cache::Entry $entry = $cache->entry( $key )\nmy $data;\nif ($entry->exists()) {\n$data = $entry->get();\n}\nelse {\n$data = getsomedata($key);\n$entry->set($data, '10 minutes');\n}", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 10, "subsections": [] }, { "name": "DESCRIPTION", "lines": 6, "subsections": [] }, { "name": "METHODS", "lines": 58, "subsections": [] }, { "name": "STORING VALIDITY OBJECTS", "lines": 8, "subsections": [] }, { "name": "STORING COMPLEX OBJECTS", "lines": 16, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "Cache::Entry - interface for a cache entry\n", "subsections": [] }, "SYNOPSIS": { "content": "my Cache::Entry $entry = $cache->entry( $key )\nmy $data;\nif ($entry->exists()) {\n$data = $entry->get();\n}\nelse {\n$data = getsomedata($key);\n$entry->set($data, '10 minutes');\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "Objects derived from Cache::Entry represent an entry in a Cache. Methods are provided that act\nupon the data in the entry, and allow you to set things like the expiry time.\n\nUsers should not create instances of Cache::Entry directly, but instead use the entry($key)\nmethod of a Cache instance.\n", "subsections": [] }, "METHODS": { "content": "my $cache = $e->cache()\nReturns a reference to the cache object this entry is from.\n\nmy $key = $e->key()\nReturns the cache key this entry is associated with.\n\nmy $bool = $e->exists()\nReturns a boolean value (1 or 0) to indicate whether there is any data present in the cache\nfor this entry.\n\n$e->set( $data, [ $expiry ] )\nStores the data into the cache. The data must be a scalar (if you want to store more complex\ndata types, see freeze and thaw below).\n\nThe expiry time may be provided as an optional 2nd argument and is in the same form as for\n'setexpiry($time)'.\n\nmy $data = $e->get()\nReturns the data from the cache, or undef if the entry doesn't exist.\n\nmy $size = $e->size()\nReturns the size of the entry data, or undef if the entry doesn't exist.\n\n$e->remove()\nClear the data for this entry from the cache.\n\nmy $expiry = $e->expiry()\nReturns the expiry time of the entry, in seconds since the epoch.\n\n$e->setexpiry( $time )\nSet the expiry time in seconds since the epoch, or alternatively using a string like '10\nminutes'. Valid units are s, second, seconds, sec, m, minute, minutes, min, h, hour, hours,\nw, week, weeks, M, month, months, y, year and years. You can also specify an absolute time,\nsuch as '16 Nov 94 22:28:20' or any other time that Date::Parse can understand. Finally, the\nstrings 'now' and 'never' may also be used.\n\nmy $fh = $e->handle( [$mode, [$expiry] ] )\nReturns an IO::Handle by which data can be read, or written, to the cache. This is useful if\nyou are caching a large amount of data - although it should be noted that only some cache\nimplementations (such as Cache::File) provide an efficient mechanism for implementing this.\n\nThe optional mode argument can be any of the perl mode strings as used for the open function\n'<', '+<', '>', '+>', '>>' and '+>>'. Alternatively it can be the corresponding fopen(3)\nmodes of 'r', 'r+', 'w', 'w+', 'a' and 'a+'. The default mode is '+<' (or 'r+') indicating\nreading and writing.\n\nThe second argument is used to set the expiry time for the entry if it doesn't exist already\nand the handle is opened for writing. It is also used to reset the expiry time if the entry\nis truncated by opening in the '>' or '+>' modes. If the expiry is not provided in these\nsituations then the default expiry time for the cache is applied.\n\nCache implementations will typically provide locking around cache entries, so that writers\nwill have have an exclusive lock and readers a shared one. Thus the method get() (or\nobtaining another handle) should be avoided whilst a write handle is held. Using set() or\nremove(), however, should be supported. These clear the current entry and whilst they do not\ninvalidate open handles, those handle will from then on refer to old data and any changes to\nthe data will be discarded.\n", "subsections": [] }, "STORING VALIDITY OBJECTS": { "content": "There are two additional set & get methods that can be used to store a validity object that is\nassociated with the data in question. Typically this is useful in conjunction with a\nvalidatecallback, and may be used to store a timestamp or similar to validate against. The\nvalidity data stored may be any complex data that can be serialized via Storable.\n\n$e->validity()\n$e->setvalidity( $data )\n", "subsections": [] }, "STORING COMPLEX OBJECTS": { "content": "The set and get methods only allow for working with simple scalar types, but if you want to\nstore more complex types they need to be serialized first. To assist with this, the freeze and\nthaw methods are provided. They are simple wrappers to get & set that use Storable to do the\nserialization and de-serialization of the data.\n\nNote, however, that you must be careful to ONLY use 'thaw' on data that was stored via 'freeze'.\nOtherwise the stored data wont actually be in Storable format and it will complain loudly.\n\n$e->freeze( $data, [ $expiry ] )\nIdentical to 'set', except that data may be any complex data type that can be serialized via\nStorable.\n\n$e->thaw()\nIdentical to 'get', except that it will return a complex data type that was set via\n'freeze'.\n", "subsections": [] }, "SEE ALSO": { "content": "Cache, Cache::File\n", "subsections": [] }, "AUTHOR": { "content": "Chris Leishman \nBased on work by DeWitt Clinton \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (C) 2003-2006 Chris Leishman. All Rights Reserved.\n\nThis module is distributed on an \"AS IS\" basis, WITHOUT WARRANTY OF ANY KIND, either expressed\nor implied. This program is free software; you can redistribute or modify it under the same\nterms as Perl itself.\n\n$Id: Entry.pm,v 1.8 2006/01/31 15:23:58 caleishm Exp $\n", "subsections": [] } } } }