{ "content": [ { "type": "text", "text": "# Cache::File (perldoc)\n\n## NAME\n\nCache::File - Filesystem based implementation of the Cache interface\n\n## SYNOPSIS\n\nuse Cache::File;\nmy $cache = Cache::File->new( cacheroot => '/tmp/mycache',\ndefaultexpires => '600 sec' );\nSee Cache for the usage synopsis.\n\n## DESCRIPTION\n\nThe Cache::File class implements the Cache interface. This cache stores data in the filesystem\nso that it can be shared between processes and persists between process invocations.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CONSTRUCTOR**\n- **METHODS**\n- **PROPERTIES**\n- **CAVEATS**\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Cache::File", "section": "", "mode": "perldoc", "summary": "Cache::File - Filesystem based implementation of the Cache interface", "synopsis": "use Cache::File;\nmy $cache = Cache::File->new( cacheroot => '/tmp/mycache',\ndefaultexpires => '600 sec' );\nSee Cache for the usage synopsis.", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 7, "subsections": [] }, { "name": "DESCRIPTION", "lines": 3, "subsections": [] }, { "name": "CONSTRUCTOR", "lines": 13, "subsections": [] }, { "name": "METHODS", "lines": 2, "subsections": [] }, { "name": "PROPERTIES", "lines": 38, "subsections": [] }, { "name": "CAVEATS", "lines": 34, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "Cache::File - Filesystem based implementation of the Cache interface\n", "subsections": [] }, "SYNOPSIS": { "content": "use Cache::File;\n\nmy $cache = Cache::File->new( cacheroot => '/tmp/mycache',\ndefaultexpires => '600 sec' );\n\nSee Cache for the usage synopsis.\n", "subsections": [] }, "DESCRIPTION": { "content": "The Cache::File class implements the Cache interface. This cache stores data in the filesystem\nso that it can be shared between processes and persists between process invocations.\n", "subsections": [] }, "CONSTRUCTOR": { "content": "my $cache = Cache::File->new( %options )\n\nThe constructor takes cache properties as named arguments, for example:\n\nmy $cache = Cache::File->new( cacheroot => '/tmp/mycache',\nlocklevel => Cache::File::LOCKLOCAL(),\ndefaultexpires => '600 sec' );\n\nNote that you MUST provide a cacheroot property.\n\nSee 'PROPERTIES' below and in the Cache documentation for a list of all available properties\nthat can be set.\n", "subsections": [] }, "METHODS": { "content": "See 'Cache' for the API documentation.\n", "subsections": [] }, "PROPERTIES": { "content": "Cache::File adds the following properties in addition to those discussed in the 'Cache'\ndocumentation.\n\ncacheroot\nUsed to specify the location of the cache store directory. All methods will work ONLY data\nstored within this directory. This parameter is REQUIRED when creating a Cache::File\ninstance.\n\nmy $ns = $c->cacheroot();\n\ncachedepth\nThe number of subdirectories deep to store cache entires. This should be large enough that\nno cache directory has more than a few hundred object. Defaults to 2 unless explicitly set.\n\nmy $depth = $c->cachedepth();\n\ncacheumask\nSpecifies the umask to use when creating entries in the cache directory. By default the\numask is '077', indicating that only the same user may access the cache files.\n\nmy $umask = $c->cacheumask();\n\nlocklevel\nSpecify the level of locking to be used. There are three different levels available:\n\nCache::File::LOCKNONE()\nNo locking is performed. Useful when you can guarantee only one process will be accessing\nthe cache at a time.\n\nCache::File::LOCKLOCAL()\nLocking is performed, but it is not suitable for use over NFS filesystems. However it is\nmore efficient.\n\nCache::File::LOCKNFS()\nLocking is performed in a way that is suitable for use on NFS filesystems.\n\nmy $level = $c->cachelocklevel();\n", "subsections": [] }, "CAVEATS": { "content": "There are a couple of caveats in the current implementation of Cache::File. None of these will\npresent a problem in using the class, it's more of a TODO list of things that could be done\nbetter.\n\nexternal cache modification (and re-syncronization)\nCache::File maintains indexes of entries in the cache, including the number of entries and\nthe total size. Currently there is no process of checking that the count or size are in\nsyncronization with the actual data on disk, and thus any modifications to the cache store\nby another program (eg. a user shell) will result in an inconsitency in the index. A better\nprocess would be for Cache::File to resyncronize at an appropriate time (eg whenever the\nsize or count is initially requested - this would only need happen once per instance). This\nresyncronization would involve calculating the total size and count as well as checking that\nentries in the index accurately reflect what is on the disk (and removing any entries that\nhave dissapeared or adding any new ones).\n\nindex efficiency\nCurrently Berkeley DB's are used for indexes of expiry time, last use and entry age. They\nuse the BTREE variant in order to implement a heap (see Cache::File::Heap). This is probably\nnot the most efficient format and having 3 separate index files adds overhead. These are\nalso cross-referenced with a fourth index file that uses a normal hash db and contains all\nthese time stamps (frozen together with the validity object to a single scalar via Storable)\nindexed by key. Needless to say, all this could be done more efficiently - probably by using\na single index in a custom format.\n\nlocking efficiency\nCurrently LOCKLOCAL is not implemented (if uses the same code as LOCKNFS).\n\nThere are two points of locking in Cache::File, index locking and entry locking. The index\nlocking is always exclusive and the lock is required briefly during most operations. The\nentry locking is either shared or exclusive and is also required during most operations.\nWhen locking is enabled, File::NFSLock is used to provide the locking for both situations.\nThis is not overly efficient, especially as the entry lock is only ever grabbed whilst the\nindex lock is held.\n", "subsections": [] }, "SEE ALSO": { "content": "Cache\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: File.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $\n", "subsections": [] } } } }