1Rose::DB::Cache(3)    User Contributed Perl Documentation   Rose::DB::Cache(3)
2
3
4

NAME

6       Rose::DB::Cache - A mod_perl-aware cache for Rose::DB objects.
7

SYNOPSIS

9         # Usage
10         package My::DB;
11
12         use base 'Rose::DB';
13         ...
14
15         $cache = My::DB->db_cache;
16
17         $db = $cache->get_db(...);
18
19         $cache->set_db($db);
20
21         $cache->clear;
22
23
24         # Subclassing
25         package My::DB::Cache;
26
27         use Rose::DB::Cache;
28         our @ISA = qw(Rose::DB::Cache);
29
30         # Override methods as desired
31         sub get_db          { ... }
32         sub set_db          { ... }
33         sub prepare_db      { ... }
34         sub build_cache_key { ... }
35         sub clear           { ... }
36         ...
37

DESCRIPTION

39       Rose::DB::Cache provides both an API and a default implementation of a
40       caching system for Rose::DB objects.  Each Rose::DB-derived class
41       references a Rose::DB::Cache-derived object to which it delegates
42       cache-related activities.  See the new_or_cached method for an example.
43
44       The default implementation caches and returns Rose::DB objects using
45       the combination of their type and domain as the cache key.  There is no
46       cache expiration or other cache cleaning.
47
48       The only sophistication in the default implementation is that it is
49       mod_perl- and Apache::DBI-aware.  When running under mod_perl, with or
50       without Apache::DBI, the dbh attribute of each cached Rose::DB object
51       is set to "undef" at the end of each request.  Additionally, any db
52       connections made in a pre-fork parent apache process are not cached.
53
54       When running under Apache::DBI, the behavior described above will
55       ensure that Apache::DBI's "ping" and rollback features work as
56       expected, keeping the DBI database handles contained within each
57       Rose::DB object connected and alive.
58
59       When running under mod_perl without Apache::DBI, the behavior described
60       above will use a single DBI database connection per cached Rose::DB
61       object per request, but will discard these connections at the end of
62       each request.
63
64       Both mod_perl 1.x and 2.x are supported.  Under mod_perl 2.x, you
65       should load Rose::DB on server startup (e.g., in your "startup.pl"
66       file).  If this is not possible, then you must explicitly tell
67       Rose::DB::Cache that apache has started up already by setting
68       apache_has_started to a true value.
69
70       Subclasses can override any and all methods described below in order to
71       implement their own caching strategy.
72

CLASS METHODS

74       apache_has_started [BOOL]
75           Get or set a boolean value indicating whether or not apache has
76           completed its startup process.  If this value is not set
77           explicitly, a best guess as to the answer will be returned.
78
79       build_cache_key PARAMS
80           Given the name/value pairs PARAMS, return a string representing the
81           corresponding cache key.  Calls to this method from within
82           Rose::DB::Cache will include at least "type" and "domain"
83           parameters, but you may pass any parameters if you override all
84           methods that call this method in your subclass.
85
86       default_use_cache_during_apache_startup [BOOL]
87           Get or set a boolean value that determines the default value of the
88           use_cache_during_apache_startup object attribute.  The default
89           value is false.  See the use_cache_during_apache_startup
90           documentation for more information.
91
92       entry_class [CLASS]
93           Get or set the name of the Rose::DB::Cache::Entry-derived class
94           used to store cached Rose::DB objects on behalf of this class.  The
95           default value is Rose::DB::Cache::Entry.
96

CONSTRUCTORS

98       new PARAMS
99           Constructs a new Rose::DB::Cache object based on PARAMS, where
100           PARAMS are name/value pairs.  Any object method is a valid
101           parameter name.
102

OBJECT METHODS

104       clear
105           Clear the cache entirely.
106
107       db_cache_entries
108           Returns a list (in list context) or reference to an array (in
109           scalar context) of cache entries for each cached db object.
110
111       db_cache_keys
112           Returns a list (in list context) or reference to an array (in
113           scalar context) of keys for each L <cache
114           entries|Rose::DB::Cache::Entry>.
115
116       get_db [PARAMS]
117           Return the cached Rose::DB-derived object corresponding to the
118           name/value pairs passed in PARAMS.  PARAMS are passed to the
119           build_cache_key method, and the key returned is used to look up the
120           cached object.
121
122           If a cached object is found, the prepare_db method is called,
123           passing the cached db object and its corresponding
124           Rose::DB::Cache::Entry object as arguments.  The cached db object
125           is then returned.
126
127           If no such object exists in the cache, undef is returned.
128
129       prepare_for_apache_fork
130           Prepares the cache for the initial fork of the apache parent
131           process by disconnect()ing all database handles and deleting all
132           cache entries that were created during apache startup.  This call
133           is only necessary if running under mod_perl and
134           use_cache_during_apache_startup set set to true.  See the
135           use_cache_during_apache_startup documentation for more information.
136
137       prepare_db [DB, ENTRY]
138           Prepare the cached Rose::DB-derived object DB for usage.  The
139           cached's db object's Rose::DB::Cache::Entry object, ENTRY, is also
140           passed.
141
142           When NOT running under mod_perl, this method does nothing.
143
144           When running under mod_perl (version 1.x or 2.x), this method will
145           do the following:
146
147           •   Any DBI database handle created inside a Rose::DB object during
148               apache server startup will be marked as such.  Any attempt to
149               use such an object after the apache startup process has
150               completed (i.e., in a child apache process) will cause it to be
151               discarded and replaced.  Note that you usually don't want it to
152               come to this.  It's better to cleanly disconnect all such
153               database handles before the first apache child forks off.  See
154               the documentation for the use_cache_during_apache_startup and
155               prepare_for_apache_fork methods for more information.
156
157           •   All DBI database handles contained in cached Rose::DB objects
158               will be cleared at the end of each request using a
159               "PerlCleanupHandler".  This will cause DBI->connect to be
160               called the next time a dbh is requested from a cached Rose::DB
161               object, which in turn will trigger Apache::DBI's ping mechanism
162               to ensure that the database handle is fresh.
163
164           Putting all the pieces together, the following implementation of
165           the init_db method in your Rose::DB::Object-derived common base
166           class will ensure that database connections are shared and fresh
167           under mod_perl and (optionally) Apache::DBI, but unshared
168           elsewhere:
169
170             package My::DB::Object;
171
172             use base 'Rose::DB::Object';
173
174             use My::DB; # isa Rose::DB
175             ...
176
177             BEGIN:
178             {
179               if($ENV{'MOD_PERL'})
180               {
181                 *init_db = sub { My::DB->new_or_cached };
182               }
183               else # act "normally" when not under mod_perl
184               {
185                 *init_db = sub { My::DB->new };
186               }
187             }
188
189       set_db DB
190           Add the Rose::DB-derived object DB to the cache.  The DB's domain,
191           type, and the db object itself (under the parameter name "db") are
192           all are passed to the build_cache_key method and the DB object is
193           stored under the key returned.
194
195           If running under mod_perl and the apache server is starting up and
196           use_cache_during_apache_startup is set to true, then the DB object
197           is not added to the cache, but merely returned.
198
199       use_cache_during_apache_startup [BOOL]
200           Get or set a boolean value that determines whether or not to cache
201           database objects during the apache server startup process.  The
202           default value is determined by the
203           default_use_cache_during_apache_startup class method.
204
205           DBI database handles created in the parent apache process cannot be
206           used in child apache processes.  Furthermore, in the case of at
207           least one one DBI driver class, you must also ensure that any
208           database handles created in the apache parent process during server
209           startup are properly disconnect()ed before you fork off the first
210           apache child.  Failure to do so may cause segmentation faults(!) in
211           child apache processes.
212
213           The upshot is that if use_cache_during_apache_startup is set to
214           true, you should call prepare_for_apache_fork at the very end of
215           the apache startup process (i.e., once all other Perl modules have
216           been loaded and all other Perl code has run).  This is usually done
217           by placing a call at the bottom of the traditional "startup.pl"
218           file.  Assuming "My::DB" is your Rose::DB-derived class:
219
220               My::DB->db_cache->prepare_for_apache_fork();
221
222           A convenience method exists in Rose::DB as well, which simply
223           translates into call shown above:
224
225               My::DB->prepare_cache_for_apache_fork();
226

AUTHOR

228       John C. Siracusa (siracusa@gmail.com)
229

LICENSE

231       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
232       program is free software; you can redistribute it and/or modify it
233       under the same terms as Perl itself.
234
235
236
237perl v5.38.0                      2023-07-21                Rose::DB::Cache(3)
Impressum