diff options
Diffstat (limited to 'lib/mnesia/doc/src/mnesia_frag_hash.xml')
| -rw-r--r-- | lib/mnesia/doc/src/mnesia_frag_hash.xml | 91 |
1 files changed, 45 insertions, 46 deletions
diff --git a/lib/mnesia/doc/src/mnesia_frag_hash.xml b/lib/mnesia/doc/src/mnesia_frag_hash.xml index 0d660925e7..fe6d847655 100644 --- a/lib/mnesia/doc/src/mnesia_frag_hash.xml +++ b/lib/mnesia/doc/src/mnesia_frag_hash.xml @@ -34,22 +34,23 @@ <file>mnesia_frag_hash.sgml</file> </header> <module>mnesia_frag_hash</module> - <modulesummary>Defines mnesia_frag_hash callback behaviour</modulesummary> + <modulesummary>Defines mnesia_frag_hash callback behavior</modulesummary> <description> - <p>The module <c>mnesia_frag_hash</c> defines a callback - behaviour for user defined hash functions of fragmented tables.</p> + <p>This module defines a callback behavior 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 + behavior 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 + <p>This module 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> + 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> + <fsummary>Initiates the hash state for a new table.</fsummary> <type> <v>Tab = atom()</v> <v>State = term()</v> @@ -57,21 +58,21 @@ <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 + <p>Starts when a fragmented table is + created with the function <c>mnesia:create_table/2</c> or + when a normal (unfragmented) 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) + <p>Notice that the function <c>add_frag/2</c> is started + one time for each of the other fragments (except 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> + <p><c>State</c> is the initial value of the <c>hash_state</c> + <c>frag_property</c>. <c>NewState</c> is 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> + <fsummary>Starts when a new fragment is added to a fragmented table.</fsummary> <type> <v>State = term()</v> <v>NewState = term()</v> @@ -80,27 +81,26 @@ <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 + <p>To scale well, it is a good idea to 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 + <p><c>NewState</c> is 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, <c>Mnesia</c> iterates over all fragments corresponding to the <c>IterFrags</c> numbers - and invoke <c>key_to_frag_number(NewState,RecordKey)</c> for + and starts <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> + fragment, the record is 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 + transaction, <c>Mnesia</c> acquires 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> + <fsummary>Starts when a fragment is deleted from a fragmented table.</fsummary> <type> <v>State = term()</v> <v>NewState = term()</v> @@ -109,39 +109,38 @@ <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 + <p><c>NewState</c> is 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, <c>Mnesia</c> iterates over all fragments corresponding to the <c>IterFrags</c> numbers - and invoke <c>key_to_frag_number(NewState,RecordKey)</c> for + and starts <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> + fragment, the record is moved to the new fragment.</p> + <p>Notice that all records in the last fragment must be moved to + another fragment, as the entire fragment is 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 + transaction, <c>Mnesia</c> acquires 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> + <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 + <p>Starts whenever <c>Mnesia</c> needs to determine which fragment a certain record belongs to. It is typically - invoked at read, write and delete.</p> + started at <c>read</c>, <c>write</c>, and <c>delete</c>.</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> + <fsummary>Resolves a <c>MatchSpec</c> into a list of fragment numbers.</fsummary> <type> <v>MatcSpec = ets_select_match_spec()</v> <v>FragNums = [FragNum]</v> @@ -149,17 +148,17 @@ <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> + <p>This function is called whenever <c>Mnesia</c> needs to determine + which fragments that need to be searched for a <c>MatchSpec</c>. + It is typically called by <c>select</c> and + <c>match_object</c>.</p> </desc> </func> </funcs> <section> <title>See Also</title> - <p>mnesia(3) - </p> + <p><seealso marker="mnesia:mnesia">mnesia(3)</seealso></p> </section> </erlref> |