net-snmp cache_handler(3)
NAME
cache_handler - Maintains a cache of data for use by lower
level handlers. Functionsnetsnmp_cache * netsnmp_cache_get_head (void)
get cache headnetsnmp_cache * netsnmp_cache_find_by_oid (oid *rootoid, int
rootoid_len)
find existing cachenetsnmp_cache * netsnmp_cache_create (int timeout,
NetsnmpCacheLoad *load_hook, NetsnmpCacheFree
*free_hook, oid *rootoid, int rootoid_len)
returns a cacheunsigned int netsnmp_cache_timer_start (netsnmp_cache
*cache)starts the recurring cache_load callback
void netsnmp_cache_timer_stop (netsnmp_cache *cache)
stops the recurring cache_load callback
netsnmp_mib_handler * netsnmp_cache_handler_get
(netsnmp_cache *cache)
returns a cache handler that can be injected into a given handler chain.netsnmp_mib_handler * netsnmp_get_cache_handler (int
timeout, NetsnmpCacheLoad *load_hook, NetsnmpCacheFree
*free_hook, oid *rootoid, int rootoid_len)
returns a cache handler that can be injected into a given handler chain.int netsnmp_cache_handler_register
(netsnmp_handler_registration *reginfo, netsnmp_cache
*cache) functionally the same as callingnetsnmp_register_handler() but also injects a cache
handler at the same time for you.int netsnmp_register_cache_handler
(netsnmp_handler_registration *reginfo, int timeout,
NetsnmpCacheLoad *load_hook, NetsnmpCacheFree
*free_hook)
functionally the same as callingnetsnmp_register_handler() but also injects a cache
handler at the same time for you.NETSNMP_STATIC_INLINE char * _build_cache_name (const char
*name)void netsnmp_cache_reqinfo_insert (netsnmp_cache *cache,
netsnmp_agent_request_info *reqinfo, const char *name)
Insert the cache information for a given request (PDU).netsnmp_cache * netsnmp_cache_reqinfo_extract
(netsnmp_agent_request_info *reqinfo, const char *name)
Extract the cache information for a given request (PDU).netsnmp_cache * netsnmp_extract_cache_info
(netsnmp_agent_request_info *reqinfo)
Version 5.4.1 Last change: 27 Jul 2007 1net-snmp cache_handler(3)
Extract the cache information for a given request (PDU).int netsnmp_cache_check_expired (netsnmp_cache *cache)
Check if the cache timeout has passed.int netsnmp_cache_check_and_reload (netsnmp_cache *cache)
Reload the cache if required.int netsnmp_cache_is_valid (netsnmp_agent_request_info
*reqinfo, const char *name) Is the cache valid for a given request?int netsnmp_is_cache_valid (netsnmp_agent_request_info
*reqinfo) for backwards compatint netsnmp_cache_helper_handler (netsnmp_mib_handler
*handler, netsnmp_handler_registration *reginfo,
netsnmp_agent_request_info *reqinfo,
netsnmp_request_info *
Implements the cache handler.void release_cached_resources (unsigned int regNo, void
*clientargs) run regularly to automatically release cached resources. Detailed Description Maintains a cache of data for use by lower level handlers. This helper checks to see whether the data has been loaded 'recently' (according to the timeout for that particularcache) and calls the registered 'load_cache' routine if
necessary. The lower handlers can then work with this local cached data.A timeout value of -1 will cause
netsnmp_cache_check_expired() to always return true, and
thus the cache will be reloaded for every request. To minimze resource use by the agent, a periodic callbackchecks for expired caches, and will call the free_cache
function for any expired cache.The load_cache route should return a negative number if the
cache was not successfully loaded. 0 or any positive number indicates successs. Several flags can be set to affect the operations on the cache.If NETSNMP_CACHE_DONT_INVALIDATE_ON_SET is set, the
free_cache method will not be called after a set request has
processed. It is assumed that the lower mib handler using the cache has maintained cache consistency.If NETSNMP_CACHE_DONT_FREE_BEFORE_LOAD is set, the
free_cache method will not be called before the load_cache
method is called. It is assumed that the load_cache routine
Version 5.4.1 Last change: 27 Jul 2007 2net-snmp cache_handler(3)
will properly deal with being called with a valid cache.If NETSNMP_CACHE_DONT_FREE_EXPIRED is set, the free_cache
method will not be called with the cache expires. The expired flag will be set, but the valid flag will not becleared. It is assumed that the load_cache routine will
properly deal with being called with a valid cache.If NETSNMP_CACHE_PRELOAD is set when a the cache handler is
created, the cache load routine will be called immediately.If NETSNMP_CACHE_DONT_AUTO_RELEASE is set, the periodic
callback that checks for expired caches will skip the cache. The cache will only be checked for expiration when a request triggers the cache handler. This is useful if the cache has it's own periodic callback to keep the cache fresh.If NETSNMP_CACHE_AUTO_RELOAD is set, a timer will be set up
to reload the cache when it expires. This is useful for keeping the cache fresh, even in the absence of incoming snmp requests. Here are some suggestions for some common situations. Cached File: If your table is based on a file that may periodically change, you can test the modification date to see if the file has changed since the last cache load. To get the cache helper to call the load function for everyrequest, set the timeout to -1, which will cause the cache
to always report that it is expired. This means that you will want to prevent the agent from flushing the cache when it has expired, and you will have to flush it manually if you detect that the file has changed. To accomplish this, set the following flags:NETSNMP_CACHE_DONT_FREE_EXPIRED
NETSNMP_CACHE_DONT_AUTO_RELEASE
Constant (periodic) reload: If you want the cache kept up to date regularly, even if no requests for the table are received, you can have your cache load routine called periodically. This is very useful if you need to monitor the data for changes (eg a LastChanged object). You will need to prevent the agent from flushing the cache when it expires. Set the cache timeout to the frequency, in seconds, that you wish to reload your cache, and set the following flags:NETSNMP_CACHE_DONT_FREE_EXPIRED
NETSNMP_CACHE_DONT_AUTO_RELEASE NETSNMP_CACHE_AUTO_RELOAD
Function Documentation Version 5.4.1 Last change: 27 Jul 2007 3net-snmp cache_handler(3)
int netsnmp_cache_check_and_reload (netsnmp_cache * cache)
Reload the cache if required.Definition at line 385 of file cache_handler.c.
References netsnmp_cache_check_expired(), and
netsnmp_cache_s::valid.
Referenced by netsnmp_cache_helper_handler().
int netsnmp_cache_check_expired (netsnmp_cache * cache)
Check if the cache timeout has passed. Sets and return the expired flag.Definition at line 370 of file cache_handler.c.
References atime_ready(), netsnmp_cache_s::expired, NULL,
netsnmp_cache_s::timeout, netsnmp_cache_s::timestamp, and
netsnmp_cache_s::valid.
Referenced by netsnmp_cache_check_and_reload(), and
release_cached_resources().
netsnmp_cache* netsnmp_cache_create (int timeout,
NetsnmpCacheLoad * load_hook, NetsnmpCacheFree * free_hook,
oid * rootoid, int rootoid_len)
returns a cacheDefinition at line 136 of file cache_handler.c.
References netsnmp_cache_s::enabled,
netsnmp_cache_s::free_cache, netsnmp_cache_s::load_cache,
netsnmp_ds_get_int(), netsnmp_cache_s::next, NULL,
netsnmp_cache_s::prev, netsnmp_cache_s::rootoid,
netsnmp_cache_s::rootoid_len, snmp_duplicate_objid(),
snmp_log(), SNMP_MALLOC_TYPEDEF, and
netsnmp_cache_s::timeout.
Referenced by netsnmp_get_cache_handler(), and
netsnmp_get_timed_bare_stash_cache_handler().
netsnmp_cache* netsnmp_cache_find_by_oid (oid * rootoid, int
rootoid_len)
find existing cacheDefinition at line 120 of file cache_handler.c.
References netsnmp_oid_equals(), netsnmp_cache_s::next,
NULL, netsnmp_cache_s::rootoid, and
netsnmp_cache_s::rootoid_len.
Version 5.4.1 Last change: 27 Jul 2007 4net-snmp cache_handler(3)
netsnmp_cache* netsnmp_cache_get_head (void)
get cache headDefinition at line 112 of file cache_handler.c.
netsnmp_mib_handler* netsnmp_cache_handler_get (netsnmp_cache *
cache) returns a cache handler that can be injected into a given handler chain.Definition at line 247 of file cache_handler.c.
References netsnmp_mib_handler_s::flags,
netsnmp_cache_s::flags, MIB_HANDLER_AUTO_NEXT,
netsnmp_mib_handler_s::myvoid,
netsnmp_cache_helper_handler(), netsnmp_cache_timer_start(),
netsnmp_create_handler(), NULL, and netsnmp_cache_s::valid.
Referenced by netsnmp_cache_handler_register(),
netsnmp_get_cache_handler(), and
netsnmp_get_timed_bare_stash_cache_handler().
int netsnmp_cache_handler_register
(netsnmp_handler_registration * reginfo, netsnmp_cache *
cache)functionally the same as calling netsnmp_register_handler()
but also injects a cache handler at the same time for you.Definition at line 295 of file cache_handler.c.
References netsnmp_cache_handler_get(),
netsnmp_inject_handler(), netsnmp_register_handler(), and
NULL.int netsnmp_cache_helper_handler (netsnmp_mib_handler *
handler, netsnmp_handler_registration * reginfo,
netsnmp_agent_request_info * reqinfo, netsnmp_request_info *
requests) Implements the cache handler.next handler called automatically - 'AUTO_NEXT'
next handler called automatically - 'AUTO_NEXT'
next handler called automatically - 'AUTO_NEXT'
Definition at line 420 of file cache_handler.c.
References netsnmp_cache_s::cache_hint,
netsnmp_cache_s::enabled, netsnmp_cache_s::flags,
netsnmp_mib_handler_s::flags, netsnmp_cache_s::free_cache,
netsnmp_handler_args_s::handler,
Version 5.4.1 Last change: 27 Jul 2007 5net-snmp cache_handler(3)
netsnmp_handler_registration_s::handlerName,
netsnmp_cache_s::load_cache, netsnmp_cache_s::magic,
MIB_HANDLER_AUTO_NEXT, netsnmp_agent_request_info_s::mode,
netsnmp_mib_handler_s::myvoid,
netsnmp_cache_check_and_reload(), netsnmp_cache_is_valid(),
netsnmp_cache_reqinfo_insert(), netsnmp_ds_get_boolean(),
netsnmp_request_set_error_all(), NULL,
netsnmp_handler_args_s::reginfo,
netsnmp_handler_args_s::reqinfo,
netsnmp_handler_args_s::requests,
netsnmp_handler_registration_s::rootoid,
netsnmp_handler_registration_s::rootoid_len, snmp_log(), and
netsnmp_cache_s::valid.
Referenced by netsnmp_cache_handler_get().
int netsnmp_cache_is_valid (netsnmp_agent_request_info *
reqinfo, const char * name) Is the cache valid for a given request?Definition at line 402 of file cache_handler.c.
References netsnmp_cache_reqinfo_extract(), and
netsnmp_cache_s::valid.
Referenced by netsnmp_cache_helper_handler(), and
netsnmp_is_cache_valid().
netsnmp_cache* netsnmp_cache_reqinfo_extract
(netsnmp_agent_request_info * reqinfo, const char * name)
Extract the cache information for a given request (PDU).Definition at line 350 of file cache_handler.c.
References _build_cache_name(),
netsnmp_agent_get_list_data(), and SNMP_FREE.
Referenced by netsnmp_cache_is_valid(),
netsnmp_extract_cache_info(), and
netsnmp_stash_cache_helper().
void netsnmp_cache_reqinfo_insert (netsnmp_cache * cache,
netsnmp_agent_request_info * reqinfo, const char * name)
Insert the cache information for a given request (PDU).Definition at line 333 of file cache_handler.c.
References _build_cache_name(),
netsnmp_agent_add_list_data(),
netsnmp_agent_get_list_data(), netsnmp_create_data_list(),
NULL, and SNMP_FREE.
Version 5.4.1 Last change: 27 Jul 2007 6net-snmp cache_handler(3)
Referenced by netsnmp_cache_helper_handler().
unsigned int netsnmp_cache_timer_start (netsnmp_cache * cache)
starts the recurring cache_load callback
Definition at line 191 of file cache_handler.c.
References netsnmp_cache_s::flags, NULL,
netsnmp_cache_s::rootoid, netsnmp_cache_s::rootoid_len,
snmp_alarm_register(), snmp_log(), netsnmp_cache_s::timeout,
and netsnmp_cache_s::timer_id.
Referenced by netsnmp_cache_handler_get().
void netsnmp_cache_timer_stop (netsnmp_cache * cache)
stops the recurring cache_load callback
Definition at line 226 of file cache_handler.c.
References netsnmp_cache_s::flags, NULL,
snmp_alarm_unregister(), snmp_log(), and
netsnmp_cache_s::timer_id.
netsnmp_cache* netsnmp_extract_cache_info
(netsnmp_agent_request_info * reqinfo)
Extract the cache information for a given request (PDU).Definition at line 362 of file cache_handler.c.
References netsnmp_cache_reqinfo_extract().
netsnmp_mib_handler* netsnmp_get_cache_handler (int timeout,
NetsnmpCacheLoad * load_hook, NetsnmpCacheFree * free_hook,
oid * rootoid, int rootoid_len)
returns a cache handler that can be injected into a given handler chain.Definition at line 276 of file cache_handler.c.
References netsnmp_mib_handler_s::myvoid,
netsnmp_cache_create(), netsnmp_cache_handler_get(), and
NULL.Referenced by netsnmp_register_cache_handler().
int netsnmp_is_cache_valid (netsnmp_agent_request_info *
reqinfo) for backwards compatnetsnmp_cache_is_valid() is preferred.
Version 5.4.1 Last change: 27 Jul 2007 7net-snmp cache_handler(3)
Definition at line 413 of file cache_handler.c.
References netsnmp_cache_is_valid().
int netsnmp_register_cache_handler
(netsnmp_handler_registration * reginfo, int timeout,
NetsnmpCacheLoad * load_hook, NetsnmpCacheFree * free_hook)
functionally the same as calling netsnmp_register_handler()
but also injects a cache handler at the same time for you.Definition at line 308 of file cache_handler.c.
References netsnmp_get_cache_handler(),
netsnmp_inject_handler(), netsnmp_register_handler(), NULL,
netsnmp_handler_registration_s::rootoid, and
netsnmp_handler_registration_s::rootoid_len.
void release_cached_resources (unsigned int regNo, void *
clientargs) run regularly to automatically release cached resources.xxx - method to prevent cache from expiring while a request
is being processed (e.g. delegated request). proposal: set a flag, which would be cleared when request finished (which could be acomplished by a dummy data list item in agent req info & custom free function).Definition at line 575 of file cache_handler.c.
References netsnmp_cache_s::flags,
netsnmp_cache_check_expired(), netsnmp_cache_s::next, NULL,
and netsnmp_cache_s::valid.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:_______________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________|__________________________________|_
| Availability | system/management/snmp/net-snmp|
|____________________|__________________________________|_
| Interface Stability| Volatile ||____________________|_________________________________|
NOTESSource for net-snmp is available on http://opensolaris.org.
Version 5.4.1 Last change: 27 Jul 2007 8