doc/classes/MCollective/Cache.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html
   3      PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8   <title>Module: MCollective::Cache</title>
   9   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  10   <meta http-equiv="Content-Script-Type" content="text/javascript" />
  11   <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
  12   <script type="text/javascript">
  13   // <![CDATA[
  14
  15   function popupCode( url ) {
  16     window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  17   }
  18
  19   function toggleCode( id ) {
  20     if ( document.getElementById )
  21       elem = document.getElementById( id );
  22     else if ( document.all )
  23       elem = eval( "document.all." + id );
  24     else
  25       return false;
  26
  27     elemStyle = elem.style;
  28
  29     if ( elemStyle.display != "block" ) {
  30       elemStyle.display = "block"
  31     } else {
  32       elemStyle.display = "none"
  33     }
  34
  35     return true;
  36   }
  37
  38   // Make codeblocks hidden by default
  39   document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  40
  41   // ]]>
  42   </script>
  43
  44 </head>
  45 <body>
  46
  47
  48
  49     <div id="classHeader">
  50         <table class="header-table">
  51         <tr class="top-aligned-row">
  52           <td><strong>Module</strong></td>
  53           <td class="class-name-in-header">MCollective::Cache</td>
  54         </tr>
  55         <tr class="top-aligned-row">
  56             <td><strong>In:</strong></td>
  57             <td>
  58                 <a href="../../files/lib/mcollective/cache_rb.html">
  59                 lib/mcollective/cache.rb
  60                 </a>
  61         <br />
  62             </td>
  63         </tr>
  64
  65         </table>
  66     </div>
  67   <!-- banner header -->
  68
  69   <div id="bodyContent">
  70
  71
  72
  73   <div id="contextContent">
  74
  75     <div id="description">
  76       <p>
  77 A class to manage a number of named caches. Each cache can have a unique
  78 timeout for keys in it and each cache has an independent Mutex protecting
  79 access to it.
  80 </p>
  81 <p>
  82 This cache is <a href="Cache.html#M000272">setup</a> early in the process
  83 of loading the mcollective libraries, before any threads are created etc
  84 making it suitable as a cross thread cache or just a store for Mutexes you
  85 need to use across threads like in an <a href="Agent.html">Agent</a> or
  86 something.
  87 </p>
  88 <pre>
  89    # sets up a new cache, noop if it already exist
  90    Cache.setup(:ddl, 600)
  91    =&gt; true
  92
  93    # writes an item to the :ddl cache, this item will
  94    # be valid on the cache for 600 seconds
  95    Cache.write(:ddl, :something, &quot;value&quot;)
  96    =&gt; &quot;value&quot;
  97
  98    # reads from the cache, read failures due to non existing
  99    # data or expired data will raise an exception
 100    Cache.read(:ddl, :something)
 101    =&gt; &quot;value&quot;
 102
 103    # time left till expiry, raises if nothing is found
 104    Cache.ttl(:ddl, :something)
 105    =&gt; 500
 106
 107    # forcibly evict something from the cache
 108    Cache.invalidate!(:ddl, :something)
 109    =&gt; &quot;value&quot;
 110
 111    # deletes an entire named cache and its mutexes
 112    Cache.delete!(:ddl)
 113    =&gt; true
 114
 115    # you can also just use this cache as a global mutex store
 116    Cache.setup(:mylock)
 117
 118    Cache.synchronize(:mylock) do
 119      do_something()
 120    end
 121 </pre>
 122
 123     </div>
 124
 125
 126    </div>
 127
 128     <div id="method-list">
 129       <h3 class="section-bar">Methods</h3>
 130
 131       <div class="name-list">
 132       <a href="#M000273">check_cache!</a>&nbsp;&nbsp;
 133       <a href="#M000275">delete!</a>&nbsp;&nbsp;
 134       <a href="#M000274">has_cache?</a>&nbsp;&nbsp;
 135       <a href="#M000280">invalidate!</a>&nbsp;&nbsp;
 136       <a href="#M000277">read</a>&nbsp;&nbsp;
 137       <a href="#M000272">setup</a>&nbsp;&nbsp;
 138       <a href="#M000279">synchronize</a>&nbsp;&nbsp;
 139       <a href="#M000278">ttl</a>&nbsp;&nbsp;
 140       <a href="#M000276">write</a>&nbsp;&nbsp;
 141       </div>
 142     </div>
 143
 144   </div>
 145
 146
 147     <!-- if includes -->
 148
 149     <div id="section">
 150
 151
 152
 153
 154
 155
 156
 157
 158     <!-- if method_list -->
 159     <div id="methods">
 160       <h3 class="section-bar">Public Class methods</h3>
 161
 162       <div id="method-M000273" class="method-detail">
 163         <a name="M000273"></a>
 164
 165         <div class="method-heading">
 166           <a href="#M000273" class="method-signature">
 167           <span class="method-name">check_cache!</span><span class="method-args">(cache_name)</span>
 168           </a>
 169         </div>
 170
 171         <div class="method-description">
 172           <p><a class="source-toggle" href="#"
 173             onclick="toggleCode('M000273-source');return false;">[Source]</a></p>
 174           <div class="method-source-code" id="M000273-source">
 175 <pre>
 176     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 70</span>
 177 70:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
 178 71:       <span class="ruby-identifier">raise_code</span>(<span class="ruby-identifier">:PLMC13</span>, <span class="ruby-value str">&quot;Could not find a cache called '%{cache_name}'&quot;</span>, <span class="ruby-identifier">:debug</span>, <span class="ruby-identifier">:cache_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">cache_name</span>) <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">has_cache?</span>(<span class="ruby-identifier">cache_name</span>)
 179 72:     <span class="ruby-keyword kw">end</span>
 180 </pre>
 181           </div>
 182         </div>
 183       </div>
 184
 185       <div id="method-M000275" class="method-detail">
 186         <a name="M000275"></a>
 187
 188         <div class="method-heading">
 189           <a href="#M000275" class="method-signature">
 190           <span class="method-name">delete!</span><span class="method-args">(cache_name)</span>
 191           </a>
 192         </div>
 193
 194         <div class="method-description">
 195           <p><a class="source-toggle" href="#"
 196             onclick="toggleCode('M000275-source');return false;">[Source]</a></p>
 197           <div class="method-source-code" id="M000275-source">
 198 <pre>
 199     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 80</span>
 200 80:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">delete!</span>(<span class="ruby-identifier">cache_name</span>)
 201 81:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
 202 82:
 203 83:       <span class="ruby-ivar">@locks_mutex</span>.<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 204 84:         <span class="ruby-ivar">@cache_locks</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">cache_name</span>)
 205 85:         <span class="ruby-ivar">@cache</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">cache_name</span>)
 206 86:       <span class="ruby-keyword kw">end</span>
 207 87:
 208 88:       <span class="ruby-keyword kw">true</span>
 209 89:     <span class="ruby-keyword kw">end</span>
 210 </pre>
 211           </div>
 212         </div>
 213       </div>
 214
 215       <div id="method-M000274" class="method-detail">
 216         <a name="M000274"></a>
 217
 218         <div class="method-heading">
 219           <a href="#M000274" class="method-signature">
 220           <span class="method-name">has_cache?</span><span class="method-args">(cache_name)</span>
 221           </a>
 222         </div>
 223
 224         <div class="method-description">
 225           <p><a class="source-toggle" href="#"
 226             onclick="toggleCode('M000274-source');return false;">[Source]</a></p>
 227           <div class="method-source-code" id="M000274-source">
 228 <pre>
 229     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 74</span>
 230 74:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">has_cache?</span>(<span class="ruby-identifier">cache_name</span>)
 231 75:       <span class="ruby-ivar">@locks_mutex</span>.<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 232 76:         <span class="ruby-ivar">@cache</span>.<span class="ruby-identifier">include?</span>(<span class="ruby-identifier">cache_name</span>)
 233 77:       <span class="ruby-keyword kw">end</span>
 234 78:     <span class="ruby-keyword kw">end</span>
 235 </pre>
 236           </div>
 237         </div>
 238       </div>
 239
 240       <div id="method-M000280" class="method-detail">
 241         <a name="M000280"></a>
 242
 243         <div class="method-heading">
 244           <a href="#M000280" class="method-signature">
 245           <span class="method-name">invalidate!</span><span class="method-args">(cache_name, key)</span>
 246           </a>
 247         </div>
 248
 249         <div class="method-description">
 250           <p><a class="source-toggle" href="#"
 251             onclick="toggleCode('M000280-source');return false;">[Source]</a></p>
 252           <div class="method-source-code" id="M000280-source">
 253 <pre>
 254      <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 139</span>
 255 139:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">invalidate!</span>(<span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">key</span>)
 256 140:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
 257 141:
 258 142:       <span class="ruby-ivar">@cache_locks</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 259 143:         <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">false</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">include?</span>(<span class="ruby-identifier">key</span>)
 260 144:
 261 145:         <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">key</span>)
 262 146:       <span class="ruby-keyword kw">end</span>
 263 147:     <span class="ruby-keyword kw">end</span>
 264 </pre>
 265           </div>
 266         </div>
 267       </div>
 268
 269       <div id="method-M000277" class="method-detail">
 270         <a name="M000277"></a>
 271
 272         <div class="method-heading">
 273           <a href="#M000277" class="method-signature">
 274           <span class="method-name">read</span><span class="method-args">(cache_name, key)</span>
 275           </a>
 276         </div>
 277
 278         <div class="method-description">
 279           <p><a class="source-toggle" href="#"
 280             onclick="toggleCode('M000277-source');return false;">[Source]</a></p>
 281           <div class="method-source-code" id="M000277-source">
 282 <pre>
 283      <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 103</span>
 284 103:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">read</span>(<span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">key</span>)
 285 104:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
 286 105:
 287 106:       <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">ttl</span>(<span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">key</span>) <span class="ruby-operator">&gt;</span> <span class="ruby-value">0</span>
 288 107:         <span class="ruby-identifier">raise_code</span>(<span class="ruby-identifier">:PLMC11</span>, <span class="ruby-value str">&quot;Cache expired on '%{cache_name}' key '%{item}'&quot;</span>, <span class="ruby-identifier">:debug</span>, <span class="ruby-identifier">:cache_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">:item</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">key</span>)
 289 108:       <span class="ruby-keyword kw">end</span>
 290 109:
 291 110:       <span class="ruby-identifier">log_code</span>(<span class="ruby-identifier">:PLMC12</span>, <span class="ruby-value str">&quot;Cache hit on '%{cache_name}' key '%{item}'&quot;</span>, <span class="ruby-identifier">:debug</span>, <span class="ruby-identifier">:cache_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">:item</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">key</span>)
 292 111:
 293 112:       <span class="ruby-ivar">@cache_locks</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 294 113:         <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>][<span class="ruby-identifier">key</span>][<span class="ruby-identifier">:value</span>]
 295 114:       <span class="ruby-keyword kw">end</span>
 296 115:     <span class="ruby-keyword kw">end</span>
 297 </pre>
 298           </div>
 299         </div>
 300       </div>
 301
 302       <div id="method-M000272" class="method-detail">
 303         <a name="M000272"></a>
 304
 305         <div class="method-heading">
 306           <a href="#M000272" class="method-signature">
 307           <span class="method-name">setup</span><span class="method-args">(cache_name, ttl=300)</span>
 308           </a>
 309         </div>
 310
 311         <div class="method-description">
 312           <p><a class="source-toggle" href="#"
 313             onclick="toggleCode('M000272-source');return false;">[Source]</a></p>
 314           <div class="method-source-code" id="M000272-source">
 315 <pre>
 316     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 56</span>
 317 56:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">setup</span>(<span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">ttl</span>=<span class="ruby-value">300</span>)
 318 57:       <span class="ruby-ivar">@locks_mutex</span>.<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 319 58:         <span class="ruby-keyword kw">break</span> <span class="ruby-keyword kw">if</span> <span class="ruby-ivar">@cache_locks</span>.<span class="ruby-identifier">include?</span>(<span class="ruby-identifier">cache_name</span>)
 320 59:
 321 60:         <span class="ruby-ivar">@cache_locks</span>[<span class="ruby-identifier">cache_name</span>] = <span class="ruby-constant">Mutex</span>.<span class="ruby-identifier">new</span>
 322 61:
 323 62:         <span class="ruby-ivar">@cache_locks</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 324 63:           <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>] = {<span class="ruby-identifier">:max_age</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-constant">Float</span>(<span class="ruby-identifier">ttl</span>)}
 325 64:         <span class="ruby-keyword kw">end</span>
 326 65:       <span class="ruby-keyword kw">end</span>
 327 66:
 328 67:       <span class="ruby-keyword kw">true</span>
 329 68:     <span class="ruby-keyword kw">end</span>
 330 </pre>
 331           </div>
 332         </div>
 333       </div>
 334
 335       <div id="method-M000279" class="method-detail">
 336         <a name="M000279"></a>
 337
 338         <div class="method-heading">
 339           <a href="#M000279" class="method-signature">
 340           <span class="method-name">synchronize</span><span class="method-args">(cache_name) {|| ...}</span>
 341           </a>
 342         </div>
 343
 344         <div class="method-description">
 345           <p><a class="source-toggle" href="#"
 346             onclick="toggleCode('M000279-source');return false;">[Source]</a></p>
 347           <div class="method-source-code" id="M000279-source">
 348 <pre>
 349      <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 129</span>
 350 129:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">synchronize</span>(<span class="ruby-identifier">cache_name</span>)
 351 130:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
 352 131:
 353 132:       <span class="ruby-identifier">raise_code</span>(<span class="ruby-identifier">:PLMC14</span>, <span class="ruby-value str">&quot;No block supplied to synchronize on cache '%{cache_name}'&quot;</span>, <span class="ruby-identifier">:debug</span>, <span class="ruby-identifier">:cache_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">cache_name</span>) <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">block_given?</span>
 354 133:
 355 134:       <span class="ruby-ivar">@cache_locks</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 356 135:         <span class="ruby-keyword kw">yield</span>
 357 136:       <span class="ruby-keyword kw">end</span>
 358 137:     <span class="ruby-keyword kw">end</span>
 359 </pre>
 360           </div>
 361         </div>
 362       </div>
 363
 364       <div id="method-M000278" class="method-detail">
 365         <a name="M000278"></a>
 366
 367         <div class="method-heading">
 368           <a href="#M000278" class="method-signature">
 369           <span class="method-name">ttl</span><span class="method-args">(cache_name, key)</span>
 370           </a>
 371         </div>
 372
 373         <div class="method-description">
 374           <p><a class="source-toggle" href="#"
 375             onclick="toggleCode('M000278-source');return false;">[Source]</a></p>
 376           <div class="method-source-code" id="M000278-source">
 377 <pre>
 378      <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 117</span>
 379 117:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">ttl</span>(<span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">key</span>)
 380 118:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
 381 119:
 382 120:       <span class="ruby-ivar">@cache_locks</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 383 121:         <span class="ruby-keyword kw">unless</span> <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">include?</span>(<span class="ruby-identifier">key</span>)
 384 122:           <span class="ruby-identifier">raise_code</span>(<span class="ruby-identifier">:PLMC15</span>, <span class="ruby-value str">&quot;No item called '%{item}' for cache '%{cache_name}'&quot;</span>, <span class="ruby-identifier">:debug</span>, <span class="ruby-identifier">:cache_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">:item</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">key</span>)
 385 123:         <span class="ruby-keyword kw">end</span>
 386 124:
 387 125:         <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>][<span class="ruby-identifier">:max_age</span>] <span class="ruby-operator">-</span> (<span class="ruby-constant">Time</span>.<span class="ruby-identifier">now</span> <span class="ruby-operator">-</span> <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>][<span class="ruby-identifier">key</span>][<span class="ruby-identifier">:cache_create_time</span>])
 388 126:       <span class="ruby-keyword kw">end</span>
 389 127:     <span class="ruby-keyword kw">end</span>
 390 </pre>
 391           </div>
 392         </div>
 393       </div>
 394
 395       <div id="method-M000276" class="method-detail">
 396         <a name="M000276"></a>
 397
 398         <div class="method-heading">
 399           <a href="#M000276" class="method-signature">
 400           <span class="method-name">write</span><span class="method-args">(cache_name, key, value)</span>
 401           </a>
 402         </div>
 403
 404         <div class="method-description">
 405           <p><a class="source-toggle" href="#"
 406             onclick="toggleCode('M000276-source');return false;">[Source]</a></p>
 407           <div class="method-source-code" id="M000276-source">
 408 <pre>
 409      <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 91</span>
 410  91:     <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">write</span>(<span class="ruby-identifier">cache_name</span>, <span class="ruby-identifier">key</span>, <span class="ruby-identifier">value</span>)
 411  92:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
 412  93:
 413  94:       <span class="ruby-ivar">@cache_locks</span>[<span class="ruby-identifier">cache_name</span>].<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
 414  95:         <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>][<span class="ruby-identifier">key</span>] <span class="ruby-operator">||=</span> {}
 415  96:         <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>][<span class="ruby-identifier">key</span>][<span class="ruby-identifier">:cache_create_time</span>] = <span class="ruby-constant">Time</span>.<span class="ruby-identifier">now</span>
 416  97:         <span class="ruby-ivar">@cache</span>[<span class="ruby-identifier">cache_name</span>][<span class="ruby-identifier">key</span>][<span class="ruby-identifier">:value</span>] = <span class="ruby-identifier">value</span>
 417  98:       <span class="ruby-keyword kw">end</span>
 418  99:
 419 100:       <span class="ruby-identifier">value</span>
 420 101:     <span class="ruby-keyword kw">end</span>
 421 </pre>
 422           </div>
 423         </div>
 424       </div>
 425
 426
 427     </div>
 428
 429
 430   </div>
 431
 432
 433 <div id="validator-badges">
 434   <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
 435 </div>
 436
 437 </body>
 438 </html>