Code Review / packages / precise / mcollective.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
Update version according to OSCI-856
[packages/precise/mcollective.git] / doc / classes / MCollective / Cache.html
diff --git a/doc/classes/MCollective/Cache.html b/doc/classes/MCollective/Cache.html
new file mode 100644 (file)
index 0000000..f3880fe
--- /dev/null
+++ b/doc/classes/MCollective/Cache.html
@@ -0,0 +1,438 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Module: MCollective::Cache</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+
+    elemStyle = elem.style;
+    
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+
+    return true;
+  }
+  
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  
+  // ]]>
+  </script>
+
+</head>
+<body>
+
+
+
+    <div id="classHeader">
+        <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>Module</strong></td>
+          <td class="class-name-in-header">MCollective::Cache</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../../files/lib/mcollective/cache_rb.html">
+                lib/mcollective/cache.rb
+                </a>
+        <br />
+            </td>
+        </tr>
+
+        </table>
+    </div>
+  <!-- banner header -->
+
+  <div id="bodyContent">
+
+
+
+  <div id="contextContent">
+
+    <div id="description">
+      <p>
+A class to manage a number of named caches. Each cache can have a unique
+timeout for keys in it and each cache has an independent Mutex protecting
+access to it.
+</p>
+<p>
+This cache is <a href="Cache.html#M000272">setup</a> early in the process
+of loading the mcollective libraries, before any threads are created etc
+making it suitable as a cross thread cache or just a store for Mutexes you
+need to use across threads like in an <a href="Agent.html">Agent</a> or
+something.
+</p>
+<pre>
+   # sets up a new cache, noop if it already exist
+   Cache.setup(:ddl, 600)
+   =&gt; true
+
+   # writes an item to the :ddl cache, this item will
+   # be valid on the cache for 600 seconds
+   Cache.write(:ddl, :something, &quot;value&quot;)
+   =&gt; &quot;value&quot;
+
+   # reads from the cache, read failures due to non existing
+   # data or expired data will raise an exception
+   Cache.read(:ddl, :something)
+   =&gt; &quot;value&quot;
+
+   # time left till expiry, raises if nothing is found
+   Cache.ttl(:ddl, :something)
+   =&gt; 500
+
+   # forcibly evict something from the cache
+   Cache.invalidate!(:ddl, :something)
+   =&gt; &quot;value&quot;
+
+   # deletes an entire named cache and its mutexes
+   Cache.delete!(:ddl)
+   =&gt; true
+
+   # you can also just use this cache as a global mutex store
+   Cache.setup(:mylock)
+
+   Cache.synchronize(:mylock) do
+     do_something()
+   end
+</pre>
+
+    </div>
+
+
+   </div>
+
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+      <a href="#M000273">check_cache!</a>&nbsp;&nbsp;
+      <a href="#M000275">delete!</a>&nbsp;&nbsp;
+      <a href="#M000274">has_cache?</a>&nbsp;&nbsp;
+      <a href="#M000280">invalidate!</a>&nbsp;&nbsp;
+      <a href="#M000277">read</a>&nbsp;&nbsp;
+      <a href="#M000272">setup</a>&nbsp;&nbsp;
+      <a href="#M000279">synchronize</a>&nbsp;&nbsp;
+      <a href="#M000278">ttl</a>&nbsp;&nbsp;
+      <a href="#M000276">write</a>&nbsp;&nbsp;
+      </div>
+    </div>
+
+  </div>
+
+
+    <!-- if includes -->
+
+    <div id="section">
+
+
+
+
+
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Class methods</h3>
+
+      <div id="method-M000273" class="method-detail">
+        <a name="M000273"></a>
+
+        <div class="method-heading">
+          <a href="#M000273" class="method-signature">
+          <span class="method-name">check_cache!</span><span class="method-args">(cache_name)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000273-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000273-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 70</span>
+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>)
+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>)
+72:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000275" class="method-detail">
+        <a name="M000275"></a>
+
+        <div class="method-heading">
+          <a href="#M000275" class="method-signature">
+          <span class="method-name">delete!</span><span class="method-args">(cache_name)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000275-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000275-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 80</span>
+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>)
+81:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
+82: 
+83:       <span class="ruby-ivar">@locks_mutex</span>.<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
+84:         <span class="ruby-ivar">@cache_locks</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">cache_name</span>)
+85:         <span class="ruby-ivar">@cache</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">cache_name</span>)
+86:       <span class="ruby-keyword kw">end</span>
+87: 
+88:       <span class="ruby-keyword kw">true</span>
+89:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000274" class="method-detail">
+        <a name="M000274"></a>
+
+        <div class="method-heading">
+          <a href="#M000274" class="method-signature">
+          <span class="method-name">has_cache?</span><span class="method-args">(cache_name)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000274-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000274-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 74</span>
+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>)
+75:       <span class="ruby-ivar">@locks_mutex</span>.<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
+76:         <span class="ruby-ivar">@cache</span>.<span class="ruby-identifier">include?</span>(<span class="ruby-identifier">cache_name</span>)
+77:       <span class="ruby-keyword kw">end</span>
+78:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000280" class="method-detail">
+        <a name="M000280"></a>
+
+        <div class="method-heading">
+          <a href="#M000280" class="method-signature">
+          <span class="method-name">invalidate!</span><span class="method-args">(cache_name, key)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000280-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000280-source">
+<pre>
+     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 139</span>
+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>)
+140:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
+141: 
+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>
+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>)
+144: 
+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>)
+146:       <span class="ruby-keyword kw">end</span>
+147:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000277" class="method-detail">
+        <a name="M000277"></a>
+
+        <div class="method-heading">
+          <a href="#M000277" class="method-signature">
+          <span class="method-name">read</span><span class="method-args">(cache_name, key)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000277-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000277-source">
+<pre>
+     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 103</span>
+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>)
+104:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
+105: 
+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>
+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>)
+108:       <span class="ruby-keyword kw">end</span>
+109: 
+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>)
+111: 
+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>
+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>]
+114:       <span class="ruby-keyword kw">end</span>
+115:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000272" class="method-detail">
+        <a name="M000272"></a>
+
+        <div class="method-heading">
+          <a href="#M000272" class="method-signature">
+          <span class="method-name">setup</span><span class="method-args">(cache_name, ttl=300)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000272-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000272-source">
+<pre>
+    <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 56</span>
+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>)
+57:       <span class="ruby-ivar">@locks_mutex</span>.<span class="ruby-identifier">synchronize</span> <span class="ruby-keyword kw">do</span>
+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>)
+59: 
+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>
+61: 
+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>
+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>)}
+64:         <span class="ruby-keyword kw">end</span>
+65:       <span class="ruby-keyword kw">end</span>
+66: 
+67:       <span class="ruby-keyword kw">true</span>
+68:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000279" class="method-detail">
+        <a name="M000279"></a>
+
+        <div class="method-heading">
+          <a href="#M000279" class="method-signature">
+          <span class="method-name">synchronize</span><span class="method-args">(cache_name) {|| ...}</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000279-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000279-source">
+<pre>
+     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 129</span>
+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>)
+130:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
+131: 
+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>
+133: 
+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>
+135:         <span class="ruby-keyword kw">yield</span>
+136:       <span class="ruby-keyword kw">end</span>
+137:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000278" class="method-detail">
+        <a name="M000278"></a>
+
+        <div class="method-heading">
+          <a href="#M000278" class="method-signature">
+          <span class="method-name">ttl</span><span class="method-args">(cache_name, key)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000278-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000278-source">
+<pre>
+     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 117</span>
+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>)
+118:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
+119: 
+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>
+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>)
+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>)
+123:         <span class="ruby-keyword kw">end</span>
+124: 
+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>])
+126:       <span class="ruby-keyword kw">end</span>
+127:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+      <div id="method-M000276" class="method-detail">
+        <a name="M000276"></a>
+
+        <div class="method-heading">
+          <a href="#M000276" class="method-signature">
+          <span class="method-name">write</span><span class="method-args">(cache_name, key, value)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p><a class="source-toggle" href="#"
+            onclick="toggleCode('M000276-source');return false;">[Source]</a></p>
+          <div class="method-source-code" id="M000276-source">
+<pre>
+     <span class="ruby-comment cmt"># File lib/mcollective/cache.rb, line 91</span>
+ 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>)
+ 92:       <span class="ruby-identifier">check_cache!</span>(<span class="ruby-identifier">cache_name</span>)
+ 93: 
+ 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>
+ 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> {}
+ 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>
+ 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>
+ 98:       <span class="ruby-keyword kw">end</span>
+ 99: 
+100:       <span class="ruby-identifier">value</span>
+101:     <span class="ruby-keyword kw">end</span>
+</pre>
+          </div>
+        </div>
+      </div>
+
+
+    </div>
+
+
+  </div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>
\ No newline at end of file