1Rose::DB::Cache(3) User Contributed Perl Documentation Rose::DB::Cache(3)
2
6 Rose::DB::Cache - A mod_perl-aware cache for Rose::DB objects.
7
9 # Usage
10 package My::DB;
11 use base 'Rose::DB';
13 ...
14 $cache = My::DB->db_cache;
16 $db = $cache->get_db(...);
18 $cache->set_db($db);
20 $cache->clear;
22 # Subclassing
25 package My::DB::Cache;
26 use Rose::DB::Cache;
28 our @ISA = qw(Rose::DB::Cache);
29 # 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
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 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 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 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 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 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 Subclasses can override any and all methods described below in order to
71 implement their own caching strategy.
72
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 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 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 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
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
104 clear
105 Clear the cache entirely.
106 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 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 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 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 If no such object exists in the cache, undef is returned.
128 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 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 When NOT running under mod_perl, this method does nothing.
143 When running under mod_perl (version 1.x or 2.x), this method will
145 do the following:
146 • 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 • 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 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 package My::DB::Object;
171 use base 'Rose::DB::Object';
173 use My::DB; # isa Rose::DB
175 ...
176 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 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 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 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 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 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 My::DB->db_cache->prepare_for_apache_fork();
221 A convenience method exists in Rose::DB as well, which simply
223 translates into call shown above:
224 My::DB->prepare_cache_for_apache_fork();
226
228 John C. Siracusa (siracusa@gmail.com)
229
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.
234perl v5.38.0 2023-07-21 Rose::DB::Cache(3)