%3 ::nx::Object ::nx::Object ::acs::Cache ::acs::Cache cache_create cache_name eval flush flush_all flush_cache flush_pattern get get_size init set show_all ::acs::Cache->::nx::Object ::acs::PartitionedCache ::acs::PartitionedCache cache_name flush_all flush_pattern_in_all_partitions init show_all ::acs::PartitionedCache->::acs::Cache ::acs::KeyPartitionedCache ::acs::KeyPartitionedCache flush_pattern set ::acs::KeyPartitionedCache->::acs::PartitionedCache

Class ::acs::Cache

::acs::Cache[i] create ... \
           [ -default_size (default "100KB") ] \
           [ -maxentry:integer maxentry:integer ] \
           [ -name name ] \
           [ -package_key:required package_key:required ] \
           [ -parameter:required parameter:required ] \
           [ -timeout (default "5m") ]
Base class for cache management
Defined in packages/acs-tcl/tcl/acs-cache-procs.tcl

Class Relations

  • class: ::nx::Class[i]
  • superclass: ::nx::Object[i]
  • subclass: ::acs::PartitionedCache[i]
::nx::Class create ::acs::Cache \
     -superclass ::nx::Object

Methods (to be applied on instances)

  • eval (scripted, public)

     <instance of acs::Cache[i]> eval [ -partition_key partition_key ] \
    [ -expires expires ] [ -timeout timeout ] [ -per_request ] key \
    command

    Evaluate the command unless the result was already computed before and cached.

    Switches:
    -partition_key (optional)
    Used for determining the cache name in partitioned caches. The partition key is computed typically automatically depending on the cache type.
    -expires (optional)
    Lifetime of the cache entry. The entry will be purged automatically when the time is reached. The time is in seconds unless a time unit is specified (e.g., 5m)
    -timeout (optional)
    Maximum time to wait for the command to complete. The time is in seconds unless a time unit is specified (e.g., 2.5m)
    -per_request (optional)
    When set, cache the result per request. So far, no attempt is made to flush the result during the lifetime of the request.
    Parameters:
    key (required)
    The cache key
    command (required)
    The command to be executed when the result is not yet cached.

    Testcases:
    No testcase defined.
    if {![info exists partition_key]} {
    set partition_key $key
}
foreach optional_parameter {expires timeout} {
    if {[info exists $optional_parameter]} {
        set ${optional_parameter}_flag [list -$optional_parameter [set $optional_parameter]]
    } else {
        set ${optional_parameter}_flag ""
    }
}
set cache_name [:cache_name $partition_key]
try {
    if {$per_request} {
        acs::per_request_cache eval -key ::acs-${cache_name}($key) {
            :uplevel [list ns_cache_eval  {*}$expires_flag {*}$timeout_flag --  $cache_name $key $command]
        }
    } else {
        :uplevel [list ns_cache_eval {*}$expires_flag {*}$timeout_flag --  $cache_name $key $command]
    }

} on break {r} {
    #
    # When the command ends with "break", it means:
    # "don't cache". We return in this case always a
    # 0.
    #
    #ns_log notice "====================== [self] $key -> break -> <$r>"
    return 0

} on ok {r} {
    return $r
}

  • flush (scripted, public)

     <instance of acs::Cache[i]> flush [ -partition_key partition_key ] \
    key

    Flush a single entry in the cache

    Switches:
    -partition_key (optional)
    Parameters:
    key (required)

    Testcases:
    No testcase defined.
    if {![info exists partition_key]} {
    set partition_key $key
}
::acs::clusterwide ns_cache flush [:cache_name $partition_key] $key

  • flush_all (scripted, public)

     <instance of acs::Cache[i]> flush_all

    Flush all contents of all (partitioned) caches. In the case of a base ::acs::Cache, it is identical to "flush_cash".

    Testcases:
    No testcase defined.
    :flush_cache

  • flush_cache (scripted, public)

     <instance of acs::Cache[i]> flush_cache \
    [ -partition_key partition_key ]

    Flush all entries in a cache.

    Switches:
    -partition_key (optional)

    Testcases:
    No testcase defined.
    ::acs::clusterwide ns_cache_flush [:cache_name $partition_key]
#ns_log notice "flush_all -> ns_cache_flush [:cache_name $partition_key]"
#ns_log notice "... content of ${:name}: [ns_cache_keys ${:name}]"

  • flush_pattern (scripted, public)

     <instance of acs::Cache[i]> flush_pattern \
    [ -partition_key partition_key ] pattern

    Flush in the cache a value based on a pattern operation. Use this function rarely, since on large caches (e.g. 100k entries or more) the glob operation will cause long locks, which should be avoided. The partitioned variants can help to reduce the lock times.

    Switches:
    -partition_key (optional)
    Parameters:
    pattern (required)

    Testcases:
    No testcase defined.
    return [::acs::clusterwide ns_cache_flush -glob [:cache_name $partition_key] $pattern]

  • get (scripted, public)

     <instance of acs::Cache[i]> get [ -partition_key partition_key ] \
    key

    The "get" method retrieves data from the cache. It should not be used for new applications due to likely race conditions, but legacy applications use this. As implementation, we use the AOLserver API emulation.

    Switches:
    -partition_key (optional)
    Parameters:
    key (required)

    Testcases:
    No testcase defined.
    if {![info exists partition_key]} {
    set partition_key $key
}
return [ns_cache get [:cache_name $partition_key] $key]

  • init (scripted, public)

     <instance of acs::Cache[i]> init

    If the name was not provided, use the object name as default.

    Testcases:
    No testcase defined.
    if {![info exists :name]} {
    set :name [namespace tail [current]]
}
:cache_create ${:name} [:get_size]

  • set (scripted, public)

     <instance of acs::Cache[i]> set [ -partition_key partition_key ] \
    key value

    Set a single value in the cache. This code uses ns_cache_eval to achieve this behavior, which is typically an AOLserver idiom and should be avoided.

    Switches:
    -partition_key (optional)
    Parameters:
    key (required)
    value (required)

    Testcases:
    No testcase defined.
    if {![info exists partition_key]} {
    set partition_key $key
}
:uplevel [list ns_cache_eval -force -- [:cache_name $partition_key] $key [list set _ $value]]

  • show_all (scripted, public)

     <instance of acs::Cache[i]> show_all

    Log all cache keys to the system log. The primary usage is for debugging.

    Testcases:
    No testcase defined.
    ns_log notice "content of ${:name}: [ns_cache_keys ${:name}]"