mc_cache()
lets you store and retrieve the results of
computation for improved performance. Each component has its own data cache
for storing one or more key/value pairs. The cache is implemented as a DBM
database. See the data caching
section of the Component Developer's Guide for examples and caching strategies.
The argument to action is one of:
o retrieve: returns the cache value if successful, or undef
if there was no value or if it has expired.
o store: stores a new cache value under the given key. Default key is 'main'.
o expire: expires a given cache value or values. key may be a single key or a list reference. Default key is 'main'.
o keys: returns a list of all the keys in the cache.
value defines what to store. It can be a scalar or a reference to an arbitrary data structure. The allowable size depends on your DBM implementation.
keep_in_memory indicates whether to save the value in memory once it is retrieved. Default is 0, meaning that the value will be retrieved from the cache file each time. If 1, each child server that retrieves this value will save its own copy, which can result in substantial memory usage for larger values. Use sparingly.
The various expiration options are:
o expire_at: takes an absolute expiration time, in Perl time()
format
(number of seconds since the epoch)
o expire_in: takes a relative expiration time of the form ``<num><unit>'', where <num> is a positive number and <unit> is one of seconds, minutes, hours, days, or weeks, or any abbreviation thereof. E.g. ``10min'', ``30m'', ``1hour''.
o expire_next: takes a string, either 'hour' or 'day'. It indicates an expiration time at the top of the next hour or day.
o expire_if: calls a given anonymous subroutine and expires if the subroutine returns a non-zero value. The subroutine is called with one parameter, the time when the cache value was last written.
<%init%>
section:
<%init> return if mc_cache_self(expire_in=>'3 hours'[, key=>'fookey']); ... <rest of init> ... </%init>
The ``return if'' is necessary. mc_cache_self handles both the retrieve and store, so you can pass both kinds of options to it. See mc_cache for an explanation of options.
mc_cache_self uses a bit of magic to accomplish everything in one line. You don't really need to understand this, but if you're curious, here's how it works:
o A component foo calls mc_cache_self for the first time.
o mc_cache_self sees that the cache is empty and calls foo again recursively, with a STORE option to capture its content into a buffer.
o foo again calls mc_cache_self; this time it returns 0 immediately.
o foo goes about its business and generates content into the mc_cache_self buffer.
o When control is returned to mc_cache_self, it stores the content in the cache and also outputs the content normally. Finally mc_cache_self returns 1, which in turn causes foo to return immediately.
<%init> if mc_call_self(my \$output, my \$retval) { ... < perform filter and return > ... } ... <rest of init> ... </%init>
See the filtering section of the Component Developer's Guide for usage and examples.
Components work exactly like Perl subroutines in terms of return values and context. A component can return any type of value, which is then returned from the mc_comp call.
If you want to capture the output of a component in a string, send a scalar reference with the STORE option. The output will be placed in the scalar instead of being sent to the default output stream.
The <& &> tag provides a convenient shortcut for mc_comp.
my $lastmod = (stat(mc_comp_source))[9];
{ package HTML::Mason::Commands; use Date::Manip; }
To allow time and date simulations in the previewer, components should use
mc_date()
rather than UnixDate directly.
mc_date()
works faster than UnixDate for some formats by
caching results.
Developers are encouraged to use relative paths whenever possible. This eliminates the need for component updates when content files are moved (the administrator just updates the static file root).
mc_file()
to resolve
relative filenames.
mc_out()
should be favored over print
or $r->print
, since mc_out()
may be redirected or buffered depending on
the current state of the interpreter.
time()
format (number of seconds since the epoch).
To allow time and date simulations in the previewer, components should use
mc_time()
rather than calling time()
directly.
mc_suppress_http_header(1)
somewhere in the <%init%>
block. You can call mc_suppress_http_header(0)
to cancel.