1cache_handler(3)                   net-snmp                   cache_handler(3)
2
3
4

NAME

6       cache_handler - Maintains a cache of data for use by lower level
7       handlers.
8
9
10   Functions
11       netsnmp_cache * netsnmp_cache_get_head (void)
12           get cache head
13       netsnmp_cache * netsnmp_cache_find_by_oid (oid *rootoid, int
14           rootoid_len)
15           find existing cache
16       netsnmp_cache * netsnmp_cache_create (int timeout, NetsnmpCacheLoad
17           *load_hook, NetsnmpCacheFree *free_hook, oid *rootoid, int
18           rootoid_len)
19           returns a cache
20       unsigned int netsnmp_cache_timer_start (netsnmp_cache *cache)
21           starts the recurring cache_load callback
22       void netsnmp_cache_timer_stop (netsnmp_cache *cache)
23           stops the recurring cache_load callback
24       netsnmp_mib_handler * netsnmp_cache_handler_get (netsnmp_cache *cache)
25           returns a cache handler that can be injected into a given handler
26           chain.
27       netsnmp_mib_handler * netsnmp_get_cache_handler (int timeout,
28           NetsnmpCacheLoad *load_hook, NetsnmpCacheFree *free_hook, oid
29           *rootoid, int rootoid_len)
30           returns a cache handler that can be injected into a given handler
31           chain.
32       int netsnmp_cache_handler_register (netsnmp_handler_registration
33           *reginfo, netsnmp_cache *cache)
34           functionally the same as calling netsnmp_register_handler() but
35           also injects a cache handler at the same time for you.
36       int netsnmp_register_cache_handler (netsnmp_handler_registration
37           *reginfo, int timeout, NetsnmpCacheLoad *load_hook,
38           NetsnmpCacheFree *free_hook)
39           functionally the same as calling netsnmp_register_handler() but
40           also injects a cache handler at the same time for you.
41       NETSNMP_STATIC_INLINE char * _build_cache_name (const char *name)
42       void netsnmp_cache_reqinfo_insert (netsnmp_cache *cache,
43           netsnmp_agent_request_info *reqinfo, const char *name)
44           Insert the cache information for a given request (PDU).
45       netsnmp_cache * netsnmp_cache_reqinfo_extract
46           (netsnmp_agent_request_info *reqinfo, const char *name)
47           Extract the cache information for a given request (PDU).
48       netsnmp_cache * netsnmp_extract_cache_info (netsnmp_agent_request_info
49           *reqinfo)
50           Extract the cache information for a given request (PDU).
51       int netsnmp_cache_check_expired (netsnmp_cache *cache)
52           Check if the cache timeout has passed.
53       int netsnmp_cache_check_and_reload (netsnmp_cache *cache)
54           Reload the cache if required.
55       int netsnmp_cache_is_valid (netsnmp_agent_request_info *reqinfo, const
56           char *name)
57           Is the cache valid for a given request?
58       int netsnmp_is_cache_valid (netsnmp_agent_request_info *reqinfo)
59           for backwards compat
60       int netsnmp_cache_helper_handler (netsnmp_mib_handler *handler,
61           netsnmp_handler_registration *reginfo, netsnmp_agent_request_info
62           *reqinfo, netsnmp_request_info *requests)
63           Implements the cache handler.
64       void release_cached_resources (unsigned int regNo, void *clientargs)
65           run regularly to automatically release cached resources.
66

Detailed Description

68       Maintains a cache of data for use by lower level handlers.
69
70       This helper checks to see whether the data has been loaded 'recently'
71       (according to the timeout for that particular cache) and calls the
72       registered 'load_cache' routine if necessary. The lower handlers can
73       then work with this local cached data.
74
75       A timeout value of -1 will cause netsnmp_cache_check_expired() to
76       always return true, and thus the cache will be reloaded for every
77       request.
78
79       To minimze resource use by the agent, a periodic callback checks for
80       expired caches, and will call the free_cache function for any expired
81       cache.
82
83       The load_cache route should return a negative number if the cache was
84       not successfully loaded. 0 or any positive number indicates successs.
85
86       Several flags can be set to affect the operations on the cache.
87
88       If NETSNMP_CACHE_DONT_INVALIDATE_ON_SET is set, the free_cache method
89       will not be called after a set request has processed. It is assumed
90       that the lower mib handler using the cache has maintained cache
91       consistency.
92
93       If NETSNMP_CACHE_DONT_FREE_BEFORE_LOAD is set, the free_cache method
94       will not be called before the load_cache method is called. It is
95       assumed that the load_cache routine will properly deal with being
96       called with a valid cache.
97
98       If NETSNMP_CACHE_DONT_FREE_EXPIRED is set, the free_cache method will
99       not be called with the cache expires. The expired flag will be set, but
100       the valid flag will not be cleared. It is assumed that the load_cache
101       routine will properly deal with being called with a valid cache.
102
103       If NETSNMP_CACHE_PRELOAD is set when a the cache handler is created,
104       the cache load routine will be called immediately.
105
106       If NETSNMP_CACHE_DONT_AUTO_RELEASE is set, the periodic callback that
107       checks for expired caches will skip the cache. The cache will only be
108       checked for expiration when a request triggers the cache handler. This
109       is useful if the cache has it's own periodic callback to keep the cache
110       fresh.
111
112       If NETSNMP_CACHE_AUTO_RELOAD is set, a timer will be set up to reload
113       the cache when it expires. This is useful for keeping the cache fresh,
114       even in the absence of incoming snmp requests.
115
116       Here are some suggestions for some common situations.
117
118       Cached File: If your table is based on a file that may periodically
119       change, you can test the modification date to see if the file has
120       changed since the last cache load. To get the cache helper to call the
121       load function for every request, set the timeout to -1, which will
122       cause the cache to always report that it is expired. This means that
123       you will want to prevent the agent from flushing the cache when it has
124       expired, and you will have to flush it manually if you detect that the
125       file has changed. To accomplish this, set the following flags:
126
127       NETSNMP_CACHE_DONT_FREE_EXPIRED NETSNMP_CACHE_DONT_AUTO_RELEASE
128
129       Constant (periodic) reload: If you want the cache kept up to date
130       regularly, even if no requests for the table are received, you can have
131       your cache load routine called periodically. This is very useful if you
132       need to monitor the data for changes (eg a LastChanged object). You
133       will need to prevent the agent from flushing the cache when it expires.
134       Set the cache timeout to the frequency, in seconds, that you wish to
135       reload your cache, and set the following flags:
136
137       NETSNMP_CACHE_DONT_FREE_EXPIRED NETSNMP_CACHE_DONT_AUTO_RELEASE
138       NETSNMP_CACHE_AUTO_RELOAD
139

Function Documentation

141   int netsnmp_cache_check_and_reload (netsnmp_cache * cache)
142       Reload the cache if required.
143
144       Definition at line 385 of file cache_handler.c.
145
146       References netsnmp_cache_check_expired(), and netsnmp_cache_s::valid.
147
148       Referenced by netsnmp_cache_helper_handler().
149
150   int netsnmp_cache_check_expired (netsnmp_cache * cache)
151       Check if the cache timeout has passed.
152
153       Sets and return the expired flag.
154
155       Definition at line 370 of file cache_handler.c.
156
157       References atime_ready(), netsnmp_cache_s::expired, NULL,
158       netsnmp_cache_s::timeout, netsnmp_cache_s::timestamp, and
159       netsnmp_cache_s::valid.
160
161       Referenced by netsnmp_cache_check_and_reload(), and
162       release_cached_resources().
163
164   netsnmp_cache* netsnmp_cache_create (int timeout, NetsnmpCacheLoad *
165       load_hook, NetsnmpCacheFree * free_hook, oid * rootoid, int
166       rootoid_len)
167       returns a cache
168
169       Definition at line 136 of file cache_handler.c.
170
171       References netsnmp_cache_s::enabled, netsnmp_cache_s::free_cache,
172       netsnmp_cache_s::load_cache, netsnmp_ds_get_int(),
173       netsnmp_cache_s::next, NULL, netsnmp_cache_s::prev,
174       netsnmp_cache_s::rootoid, netsnmp_cache_s::rootoid_len,
175       snmp_duplicate_objid(), snmp_log(), SNMP_MALLOC_TYPEDEF, and
176       netsnmp_cache_s::timeout.
177
178       Referenced by netsnmp_get_cache_handler(), and
179       netsnmp_get_timed_bare_stash_cache_handler().
180
181   netsnmp_cache* netsnmp_cache_find_by_oid (oid * rootoid, int rootoid_len)
182       find existing cache
183
184       Definition at line 120 of file cache_handler.c.
185
186       References netsnmp_oid_equals(), netsnmp_cache_s::next,
187       netsnmp_cache_s::rootoid, and netsnmp_cache_s::rootoid_len.
188
189   netsnmp_cache* netsnmp_cache_get_head (void)
190       get cache head
191
192       Definition at line 112 of file cache_handler.c.
193
194   netsnmp_mib_handler* netsnmp_cache_handler_get (netsnmp_cache * cache)
195       returns a cache handler that can be injected into a given handler
196       chain.
197
198       Definition at line 247 of file cache_handler.c.
199
200       References netsnmp_mib_handler_s::flags, netsnmp_cache_s::flags,
201       MIB_HANDLER_AUTO_NEXT, netsnmp_mib_handler_s::myvoid,
202       netsnmp_cache_helper_handler(), netsnmp_cache_timer_start(),
203       netsnmp_create_handler(), NULL, and netsnmp_cache_s::valid.
204
205       Referenced by netsnmp_cache_handler_register(),
206       netsnmp_get_cache_handler(), and
207       netsnmp_get_timed_bare_stash_cache_handler().
208
209   int netsnmp_cache_handler_register (netsnmp_handler_registration * reginfo,
210       netsnmp_cache * cache)
211       functionally the same as calling netsnmp_register_handler() but also
212       injects a cache handler at the same time for you.
213
214       Definition at line 295 of file cache_handler.c.
215
216       References netsnmp_cache_handler_get(), netsnmp_inject_handler(),
217       netsnmp_register_handler(), and NULL.
218
219   int netsnmp_cache_helper_handler (netsnmp_mib_handler * handler,
220       netsnmp_handler_registration * reginfo, netsnmp_agent_request_info *
221       reqinfo, netsnmp_request_info * requests)
222       Implements the cache handler.
223
224       next handler called automatically - 'AUTO_NEXT'
225
226       next handler called automatically - 'AUTO_NEXT'
227
228       next handler called automatically - 'AUTO_NEXT'
229
230       Definition at line 420 of file cache_handler.c.
231
232       References netsnmp_cache_s::cache_hint, netsnmp_cache_s::enabled,
233       netsnmp_cache_s::flags, netsnmp_mib_handler_s::flags,
234       netsnmp_cache_s::free_cache, netsnmp_handler_args_s::handler,
235       netsnmp_handler_registration_s::handlerName,
236       netsnmp_cache_s::load_cache, netsnmp_cache_s::magic,
237       MIB_HANDLER_AUTO_NEXT, netsnmp_agent_request_info_s::mode,
238       netsnmp_mib_handler_s::myvoid, netsnmp_cache_check_and_reload(),
239       netsnmp_cache_is_valid(), netsnmp_cache_reqinfo_insert(),
240       netsnmp_ds_get_boolean(), netsnmp_request_set_error_all(), NULL,
241       netsnmp_handler_args_s::reginfo, netsnmp_handler_args_s::reqinfo,
242       netsnmp_handler_args_s::requests,
243       netsnmp_handler_registration_s::rootoid,
244       netsnmp_handler_registration_s::rootoid_len, snmp_log(), and
245       netsnmp_cache_s::valid.
246
247       Referenced by netsnmp_cache_handler_get().
248
249   int netsnmp_cache_is_valid (netsnmp_agent_request_info * reqinfo, const
250       char * name)
251       Is the cache valid for a given request?
252
253       Definition at line 402 of file cache_handler.c.
254
255       References netsnmp_cache_reqinfo_extract(), and netsnmp_cache_s::valid.
256
257       Referenced by netsnmp_cache_helper_handler(), and
258       netsnmp_is_cache_valid().
259
260   netsnmp_cache* netsnmp_cache_reqinfo_extract (netsnmp_agent_request_info *
261       reqinfo, const char * name)
262       Extract the cache information for a given request (PDU).
263
264       Definition at line 350 of file cache_handler.c.
265
266       References _build_cache_name(), netsnmp_agent_get_list_data(), and
267       SNMP_FREE.
268
269       Referenced by netsnmp_cache_is_valid(), netsnmp_extract_cache_info(),
270       and netsnmp_stash_cache_helper().
271
272   void netsnmp_cache_reqinfo_insert (netsnmp_cache * cache,
273       netsnmp_agent_request_info * reqinfo, const char * name)
274       Insert the cache information for a given request (PDU).
275
276       Definition at line 333 of file cache_handler.c.
277
278       References _build_cache_name(), netsnmp_agent_add_list_data(),
279       netsnmp_agent_get_list_data(), netsnmp_create_data_list(), NULL, and
280       SNMP_FREE.
281
282       Referenced by netsnmp_cache_helper_handler().
283
284   unsigned int netsnmp_cache_timer_start (netsnmp_cache * cache)
285       starts the recurring cache_load callback
286
287       Definition at line 191 of file cache_handler.c.
288
289       References netsnmp_cache_s::flags, NULL, netsnmp_cache_s::rootoid,
290       netsnmp_cache_s::rootoid_len, snmp_alarm_register(), snmp_log(),
291       netsnmp_cache_s::timeout, and netsnmp_cache_s::timer_id.
292
293       Referenced by netsnmp_cache_handler_get().
294
295   void netsnmp_cache_timer_stop (netsnmp_cache * cache)
296       stops the recurring cache_load callback
297
298       Definition at line 226 of file cache_handler.c.
299
300       References netsnmp_cache_s::flags, NULL, snmp_alarm_unregister(),
301       snmp_log(), and netsnmp_cache_s::timer_id.
302
303   netsnmp_cache* netsnmp_extract_cache_info (netsnmp_agent_request_info *
304       reqinfo)
305       Extract the cache information for a given request (PDU).
306
307       Definition at line 362 of file cache_handler.c.
308
309       References netsnmp_cache_reqinfo_extract().
310
311   netsnmp_mib_handler* netsnmp_get_cache_handler (int timeout,
312       NetsnmpCacheLoad * load_hook, NetsnmpCacheFree * free_hook, oid *
313       rootoid, int rootoid_len)
314       returns a cache handler that can be injected into a given handler
315       chain.
316
317       Definition at line 276 of file cache_handler.c.
318
319       References netsnmp_mib_handler_s::myvoid, netsnmp_cache_create(),
320       netsnmp_cache_handler_get(), and NULL.
321
322       Referenced by netsnmp_register_cache_handler().
323
324   int netsnmp_is_cache_valid (netsnmp_agent_request_info * reqinfo)
325       for backwards compat
326
327       netsnmp_cache_is_valid() is preferred.
328
329       Definition at line 413 of file cache_handler.c.
330
331       References netsnmp_cache_is_valid().
332
333   int netsnmp_register_cache_handler (netsnmp_handler_registration * reginfo,
334       int timeout, NetsnmpCacheLoad * load_hook, NetsnmpCacheFree *
335       free_hook)
336       functionally the same as calling netsnmp_register_handler() but also
337       injects a cache handler at the same time for you.
338
339       Definition at line 308 of file cache_handler.c.
340
341       References netsnmp_get_cache_handler(), netsnmp_inject_handler(),
342       netsnmp_register_handler(), NULL,
343       netsnmp_handler_registration_s::rootoid, and
344       netsnmp_handler_registration_s::rootoid_len.
345
346   void release_cached_resources (unsigned int regNo, void * clientargs)
347       run regularly to automatically release cached resources.
348
349       xxx - method to prevent cache from expiring while a request is being
350       processed (e.g. delegated request). proposal: set a flag, which would
351       be cleared when request finished (which could be acomplished by a dummy
352       data list item in agent req info & custom free function).
353
354       Definition at line 577 of file cache_handler.c.
355
356       References netsnmp_cache_s::flags, netsnmp_cache_check_expired(),
357       netsnmp_cache_s::next, NULL, and netsnmp_cache_s::valid.
358
359
360
361Version 5.4                       24 Nov 2006                 cache_handler(3)