diff options
Diffstat (limited to 'lib/mnesia/doc/src/mnesia_frag_hash.xml')
| -rw-r--r-- | lib/mnesia/doc/src/mnesia_frag_hash.xml | 166 |
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å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> + |