{
    "content": [
        {
            "type": "text",
            "text": "# Cache (man)\n\n## NAME\n\nCache - the Cache interface\n\n## DESCRIPTION\n\nThe Cache modules are designed to assist a developer in persisting data for a specified\nperiod of time.  Often these modules are used in web applications to store data locally to\nsave repeated and redundant expensive calls to remote machines or databases.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **USAGE**\n- **METHODS**\n- **PROPERTIES**\n- **SHORTCUT METHODS**\n- **TIE INTERFACE**\n- **REMOVAL STRATEGY METHODS**\n- **UTILITY METHODS**\n- **SEE ALSO** (1 subsections)\n- **AUTHOR**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Cache",
        "section": "",
        "mode": "man",
        "summary": "Cache - the Cache interface",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "USAGE",
                "lines": 22,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 17,
                "subsections": []
            },
            {
                "name": "PROPERTIES",
                "lines": 41,
                "subsections": []
            },
            {
                "name": "SHORTCUT METHODS",
                "lines": 17,
                "subsections": []
            },
            {
                "name": "TIE INTERFACE",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "REMOVAL STRATEGY METHODS",
                "lines": 21,
                "subsections": []
            },
            {
                "name": "UTILITY METHODS",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": [
                    {
                        "name": "DIFFERENCES FROM CACHE::CACHE",
                        "lines": 23
                    }
                ]
            },
            {
                "name": "AUTHOR",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 11,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Cache - the Cache interface\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "The Cache modules are designed to assist a developer in persisting data for a specified\nperiod of time.  Often these modules are used in web applications to store data locally to\nsave repeated and redundant expensive calls to remote machines or databases.\n\nThe Cache interface is implemented by derived classes that store cached data in different\nmanners (such as files on a filesystem, or in memory).\n",
                "subsections": []
            },
            "USAGE": {
                "content": "To use the Cache system, a cache implementation must be chosen to suit your needs.  The most\ncommon is Cache::File, which is suitable for sharing data between multiple invocations and\neven between concurrent processes.\n\nUsing a cache is simple.  Here is some very simple sample code for instantiating and using a\nfile system based cache.\n\nuse Cache::File;\n\nmy $cache = Cache::File->new( cacheroot => '/tmp/cacheroot' );\nmy $customer = $cache->get( $name );\n\nunless ($customer) {\n$customer = getcustomerfromdb( $name );\n$cache->set( $name, $customer, '10 minutes' );\n}\n\nreturn $customer;\n\nOf course, far more powerful methods are available for accessing cached data.  Also see the\nTIE INTERFACE below.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "my $cacheentry = $c->entry( $key )\nReturn a 'Cache::Entry' object for the given key.  This object can then be used to\nmanipulate the cache entry in various ways.  The key can be any scalar string that will\nuniquely identify an entry in the cache.\n\n$c->purge()\nRemove all expired data from the cache.\n\n$c->clear()\nRemove all entries from the cache - regardless of their expiry time.\n\nmy $num = $c->count()\nReturns the number of entries in the cache.\n\nmy $size = $c->size()\nReturns the size (in bytes) of the cache.\n",
                "subsections": []
            },
            "PROPERTIES": {
                "content": "When a cache is constructed these properties can be supplied as options to the new() method.\n\ndefaultexpires\nThe current default expiry time for new entries into the cache.  This property can also\nbe reset at any time.\n\nmy $time = $c->defaultexpires();\n$c->setdefaultexpires( $expiry );\n\nremovalstrategy\nThe removal strategy object for the cache.  This is used to remove object from the cache\nin order to maintain the cache size limit.\n\nWhen setting the removal strategy in new(), the name of a strategy package or a blessed\nstrategy object reference should be provided  (in the former case an object is\nconstructed by calling the new() method of the named package).\n\nThe strategies 'Cache::RemovalStrategy::LRU' and 'Cache::RemovalStrategy::FIFO' are\navailable by default.\n\nmy $strategy = $c->removalstrategy();\n\nsizelimit\nThe size limit for the cache.\n\nmy $limit = $c->sizelimit();\n\nloadcallback\nThe load callback for the cache.  This may be set to a function that will get called\nanytime a 'get' is issued for data that does not exist in the cache.\n\nmy $limit = $c->loadcallback();\n$c->setloadcallback($callbackfunc);\n\nvalidatecallback\nThe validate callback for the cache.  This may be set to a function that will get called\nanytime a 'get' is issued for data that does not exist in the cache.\n\nmy $limit = $c->validatecallback();\n$c->setvalidatecallback($callbackfunc);\n",
                "subsections": []
            },
            "SHORTCUT METHODS": {
                "content": "These methods all have counterparts in the Cache::Entry package, but are provided here as\nshortcuts.  They all default to just wrappers that do '$c->entry($key)->methodname()'.  For\ndocumentation, please refer to Cache::Entry.\n\nmy $bool = $c->exists( $key )\n$c->set( $key, $data, [ $expiry ] )\nmy $data = $c->get( $key )\nmy $data = $c->size( $key )\n$c->remove( $key )\n$c->expiry( $key )\n$c->setexpiry( $key, $time )\n$c->handle( $key, [$mode, [$expiry] ] )\n$c->validity( $key )\n$c->setvalidity( $key, $data )\n$c->freeze( $key, $data, [ $expiry ] )\n$c->thaw( $key )\n",
                "subsections": []
            },
            "TIE INTERFACE": {
                "content": "tie %hash, 'Cache::File', { cacheroot => $tempdir };\n\n$hash{'key'} = 'some data';\n$data = $hash{'key'};\n\nThe Cache classes can be used via the tie interface, as shown in the synopsis.  This allows\nthe cache to be accessed via a hash.  All the standard methods for accessing the hash are\nsupported , with the exception of the 'keys' or 'each' call.\n\nThe tie interface is especially useful with the loadcallback to automatically populate the\nhash.\n",
                "subsections": []
            },
            "REMOVAL STRATEGY METHODS": {
                "content": "These methods are only for use internally (by concrete Cache implementations).\n\nThese methods define the interface by which the removal strategy object can manipulate the\ncache (the Cache is the 'context' of the strategy).  By default, methods need to be provided\nto remove the oldest or stalest objects in the cache - thus allowing support for the default\nFIFO and LRU removal strategies.  All derived Cache implementations should support these\nmethods and may also introduce additional methods (and additional removal strategies to\nmatch).\n\nmy $size = $c->removeoldest()\nRemoves the oldest entry in the cache and returns its size.\n\nmy $size = $c->removestalest()\nRemoves the 'stalest' (least used) object in the cache and returns its size.\n\n$c->checksize( $size )\nThis method isn't actually part of the strategy interface, nor does it need to be defined\nby Cache implementations.  Instead it should be called by implementations whenever the\nsize of the cache increases.  It will take care of checking the size limit and invoking\nthe removal strategy if required.  The size argument should be the new size of the cache.\n",
                "subsections": []
            },
            "UTILITY METHODS": {
                "content": "These methods are only for use internally (by concrete Cache implementations).\n\nmy $time = Cache::CanonicalizeExpirationTime($timespec)\nConverts a timespec as described for Cache::Entry::setexpiry() into a unix time.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Cache::Entry, Cache::File, Cache::RemovalStrategy\n",
                "subsections": [
                    {
                        "name": "DIFFERENCES FROM CACHE::CACHE",
                        "content": "The Cache modules are a total redesign and reimplementation of Cache::Cache and thus not\ndirectly compatible.  It would be, however, quite possible to write a wrapper module that\nprovides an identical interface to Cache::Cache.\n\nThe semantics of use are very similar to Cache::Cache, with the following exceptions:\n\nThe get/set methods DO NOT serialize complex data types.  Use freeze/thaw instead (but read\nthe notes in Cache::Entry).\nThe getobject / setobject methods are not available, but have been superseded by the more\nflexible entry method and Cache::Entry class.\nThere is no concept of 'namespace' in the basic cache interface, although implementations\n(eg. Cache::Memory) may choose to provide them.  For instance, File::Cache does not provide\nthis - but different namespaces can be created by varying cacheroot.\nIn the current Cache implementations purging is done automatically - there is no need to\nexplicitly enable auto purge on get/set.  The purging algorithm is no longer implemented in\nthe base Cache class, but is left up to the implementations and may thus be implemented in\nthe most efficient way for the storage medium.\nCache::SharedMemory is not yet available.\nCache::File no longer supports separate masks for entries and directories.  It is not a very\nsecure configuration and presents numerous issues for cache consistency and is hence\ndeprecated.  There is still some work to be done to ensure cache consistency between accesses\nby different users.\n"
                    }
                ]
            },
            "AUTHOR": {
                "content": "Chris Leishman <chris@leishman.org>\nBased on work by DeWitt Clinton <dewitt@unto.net>\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\nexpressed or implied. This program is free software; you can redistribute or modify it under\nthe same terms as Perl itself.\n\n$Id: Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $\n\n\n\nperl v5.32.0                                 2021-01-01                                   Cache(3pm)",
                "subsections": []
            }
        }
    }
}