The R13B03 release.OTP_R13B03

1 files changed, 166 insertions, 0 deletions

diff --git a/lib/mnesia/doc/src/mnesia_frag_hash.xml b/lib/mnesia/doc/src/mnesia_frag_hash.xml
new file mode 100644
index 0000000000..ca03327994
--- /dev/null
+++ b/lib/mnesia/doc/src/mnesia_frag_hash.xml
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2002</year>
+      <year>2007</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>mnesia_frag_hash</title>
+    <prepared>H&aring;kan Mattsson</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>2002-09-10</date>
+    <rev>A</rev>
+    <file>mnesia_frag_hash.sgml</file>
+  </header>
+  <module>mnesia_frag_hash</module>
+  <modulesummary>Defines mnesia_frag_hash callback behaviour</modulesummary>
+  <description>
+    <p>The module <c>mnesia_frag_hash</c> defines a callback
+      behaviour for user defined hash functions of fragmented tables.</p>
+    <p>Which module that is selected to implement the <c>mnesia_frag_hash</c>
+      behaviour for a particular fragmented table is specified together
+      with the other <c>frag_properties</c>. The <c>hash_module</c> defines
+      the module name. The <c>hash_state</c> defines the initial hash state.</p>
+    <p>It implements dynamic hashing which is a kind of hashing
+      that grows nicely when new fragments are added. It is well
+      suited for scalable hash tables</p>
+  </description>
+  <funcs>
+    <func>
+      <name>init_state(Tab, State) -> NewState | abort(Reason)</name>
+      <fsummary>Initiate the hash state for a new table</fsummary>
+      <type>
+        <v>Tab = atom()</v>
+        <v>State = term()</v>
+        <v>NewState = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>This function is invoked when a fragmented table is
+          created with <c>mnesia:create_table/2</c> or when a
+          normal (un-fragmented) table is converted to be a
+          fragmented table with <c>mnesia:change_table_frag/2</c>.</p>
+        <p>Note that the <c>add_frag/2</c> function will be invoked
+          one time each for the rest of the fragments (all but number 1)
+          as a part of the table creation procedure.</p>
+        <p><c>State</c> is the initial value of the <c>hash_state</c><c>frag_property</c>. The <c>NewState</c> will be stored as
+          <c>hash_state</c> among the other <c>frag_properties</c>.
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name>add_frag(State) -> {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)</name>
+      <fsummary>This function is invoked when a new fragment is added to a fragmented table</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>NewState = term()</v>
+        <v>IterFrags = [integer()]</v>
+        <v>AdditionalLockFrags = [integer()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>In order to scale well, it is a good idea ensure that the
+          records are evenly distributed over all fragments including
+          the new one.</p>
+        <p>The <c>NewState</c> will be stored as <c>hash_state</c> among the
+          other <c>frag_properties</c>. 
+          </p>
+        <p>As a part of the <c>add_frag</c> procedure, Mnesia will iterate
+          over all fragments corresponding to the <c>IterFrags</c> numbers
+          and invoke <c>key_to_frag_number(NewState,RecordKey)</c> for
+          each record. If the new fragment differs from the old
+          fragment, the record will be moved to the new fragment.</p>
+        <p>As the <c>add_frag</c> procedure is a part of a schema
+          transaction Mnesia will acquire a write locks on the
+          affected tables. That is both the fragments corresponding
+          to <c>IterFrags</c> and those corresponding to
+          <c>AdditionalLockFrags</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>del_frag(State) ->  {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)</name>
+      <fsummary>This function is invoked when a fragment is deleted from a fragmented table</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>NewState = term()</v>
+        <v>IterFrags = [integer()]</v>
+        <v>AdditionalLockFrags = [integer()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>The <c>NewState</c> will be stored as <c>hash_state</c> among the
+          other <c>frag_properties</c>. 
+          </p>
+        <p>As a part of the <c>del_frag</c> procedure, Mnesia will iterate
+          over all fragments corresponding to the <c>IterFrags</c> numbers
+          and invoke <c>key_to_frag_number(NewState,RecordKey)</c> for
+          each record. If the new fragment differs from the old
+          fragment, the record will be moved to the new fragment.</p>
+        <p>Note that all records in the last fragment must be moved to
+          another fragment as the entire fragment will be deleted.</p>
+        <p>As the <c>del_frag</c> procedure is a part of a schema
+          transaction Mnesia will acquire a write locks on the
+          affected tables. That is both the fragments corresponding
+          to <c>IterFrags</c> and those corresponding to
+          <c>AdditionalLockFrags</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>key_to_frag_number(State, Key) -> FragNum | abort(Reason)</name>
+      <fsummary>Resolves the key of a record into a fragment number</fsummary>
+      <type>
+        <v>FragNum = integer()()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>This function is invoked whenever Mnesia needs to determine
+          which fragment a certain record belongs to. It is typically
+          invoked at read, write and delete.</p>
+      </desc>
+    </func>
+    <func>
+      <name>match_spec_to_frag_numbers(State, MatchSpec) -> FragNums | abort(Reason)</name>
+      <fsummary>Resolves a MatchSpec into a list of fragment numbers</fsummary>
+      <type>
+        <v>MatcSpec = ets_select_match_spec()</v>
+        <v>FragNums = [FragNum]</v>
+        <v>FragNum = integer()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>This function is invoked whenever Mnesia needs to determine
+          which fragments that needs to be searched for a MatchSpec.
+          It is typically invoked at select and match_object.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>See Also</title>
+    <p>mnesia(3)
+      </p>
+  </section>
+  
+</erlref>
+