mc_cache()
and mc_cache_self()
let 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.
The argument to action is one of 'retrieve' or 'store'. Default is 'retrieve'.
The retrieve action returns the cache value if successful, or undef
if there was no value or if it has expired.
The store action stores a new cache value, under the given key. The default key is 'main'.
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 sec, seconds, min, minutes, hours, days, weeks, or months. You can also use the first letter or singular form of any of these. (This notation was adapted from Sullivan Beck's Date::Manip package.) E.g. ``30sec'', ``10min'', ``1hour'', ``4h''.
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.
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.
{ 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 data files are moved (the administrator just updates the static file root).
mc_file()
to resolve
relative filenames.
mc_out()
should be favored over the lower-level $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 <%perl_init%>
block. You can call mc_suppress_http_header(0)
to cancel.