Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

cache::async(n)                               In-memory caches                               cache::async(n)



____________________________________________________________________________________________________________

NAME
       cache::async - Asynchronous in-memory cache

SYNOPSIS
       package require Tcl  8.4

       package require cache::async  ?0.3?

       ::cache::async objectName commandprefix ?options...?

       objectName get key donecmdprefix

       objectName set key value

       objectName unset key

       objectName exists key

       objectName clear ?key?

____________________________________________________________________________________________________________

DESCRIPTION
       This  package  provides objects which cache data in memory, and operate asynchronously with regard to
       request and responses. The objects are agnostic with regard to cache keys  and  values,  and  unknown
       methods are delegated to the provider of cached data. These two properties make it easy to use caches
       as a facade for any data provider.

API
       The package exports a class, cache::async, as specified below.

       ::cache::async objectName commandprefix ?options...?
              The command creates a new cache object with an associated global Tcl  command  whose  name  is
              objectName.  This command may be used to invoke various operations on the object.

              The  commandprefix  is  the  action to perform when an user asks for data in the cache and the
              cache doesn't yet know about the key. When run the commandprefix  is  given  three  additional
              arguments,  the string get, the key requested, and the cache object itself, in the form of its
              object command, in this order. The execution of the action is done in an idle-handler,  decou-pling decoupling
              pling it from the original request.

              The only supported option is

              -full-async-results
                     This option defines the behaviour of the cache for when requested keys are known to the
                     cache at the time of get request. By default  such  requeste  are  responded  to  asyn-chronously asynchronously
                     chronously  as  well.  Setting this option to false forces the cache to respond to them
                     synchronuously, although still through the specified callback.

       The object commands created by the class commands above have the form:

       objectName get key donecmdprefix
              This method requests the data for the key from the cache. If the data is  not  yet  known  the
              command  prefix  specified  during  construction  of  the cache object is used to ask for this
              information.

              Whenever the information is/becomes available the donecmdprefix will be run  to  transfer  the
              result to the caller. This command prefix is invoked with either 2 or 3 arguments, i.e.

              [1]    The string set, the key, and the value.

              [2]    The string unset, and the key.
       These two possibilities are used to either signal the value for the key, or that the key has no value
       defined for it. The latter is distinct from the cache not knowing about the key.

       For a cache object configured to be fully asynchronous (default) the donecmdprefix is always  run  in
       an idle-handler, decoupling it from the request. Otherwise the callback will be invoked synchronously
       when the key is known to the cache at the time of the invokation.

       Another important part of the cache's behaviour, as it is asynchronous it is possible  that  multiple
       get  requests  are  issued  for the same key before it can respond. In that case the cache will issue
       only one data request to the provider, for the first of these,  and  suspend  the  others,  and  then
       notify all of them when the data becomes available.

       objectName set key value

       objectName unset key
              These two methods are provided to allow users of the cache to make keys known to the cache, as
              either having a value, or as undefined.

              It is expected that the data provider (see commandprefix of  the  constructor)  uses  them  in
              response to data requests for unknown keys.

              Note  how  this  matches  the  cache's own API towards its caller, calling the donecmd of get-requests getrequests
              requests issued to itself with either "set key value" or  "unset  key",  versus  issuing  get-requests getrequests
              requests  to  its own provider with itself in the place of the donecmd, expecting to be called
              with either "set key value" or "unset key".

              This also means that these methods invoke the donecmd of all get-requests waiting for informa-tion information
              tion about the modified key.

       objectName exists key
              This  method  queries  the  cache for knowledge about the key and returns a boolean value. The
              result is true if the key is known, and false otherwise.

       objectName clear ?key?
              This method resets the state of either the specified key or of all keys known  to  the  cache,
              making it unkown. This forces future get-requests to reload the information from the provider.


BUGS, IDEAS, FEEDBACK
       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other  problems.
       Please   report   such   in   the   category   cache   of  the  Tcllib  SF  Trackers  [http://source -
       forge.net/tracker/? group_id=12883].  Please also report any ideas for enhancements you may  have  for
       either package and/or documentation.

KEYWORDS
       asynchronous, cache, callback, synchronous

COPYRIGHT
       Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>




cache                                                0.3                                     cache::async(n)