File: mnesia_frag_hash.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (210 lines) | stat: -rw-r--r-- 6,745 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>mnesia_frag_hash</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>mnesia_frag_hash</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
mnesia_frag_hash
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Defines mnesia_frag_hash callback behaviour
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>The module <CODE>mnesia_frag_hash</CODE> defines a callback
        behaviour for user defined hash functions of fragmented tables.
<P>Which module that is selected to implement the <CODE>mnesia_frag_hash</CODE>
behaviour for a particular fragmented table is specified together
with the other <CODE>frag_properties</CODE>. The <CODE>hash_module</CODE> defines
the module name. The <CODE>hash_state</CODE> defines the initial hash state.
<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
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="init_state/2"><STRONG><CODE>init_state(Tab, State) -&#62; NewState | abort(Reason)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Tab = atom()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is invoked when a fragmented table is
created with <CODE>mnesia:create_table/2</CODE> or when a
normal (un-fragmented) table is converted to be a
fragmented table with <CODE>mnesia:change_table_frag/2</CODE>.
<P>Note that the <CODE>add_frag/2</CODE> 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><CODE>State</CODE> is the initial value of the <CODE>hash_state</CODE>
         <CODE>frag_property</CODE>. The <CODE>NewState</CODE> will be stored as
<CODE>hash_state</CODE> among the other <CODE>frag_properties</CODE>.


</DIV>

<P><A NAME="add_frag/1"><STRONG><CODE>add_frag(State) -&#62; {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>IterFrags = [integer()]</CODE></STRONG><BR>
<STRONG><CODE>AdditionalLockFrags = [integer()]</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<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>The <CODE>NewState</CODE> will be stored as <CODE>hash_state</CODE> among the
other <CODE>frag_properties</CODE>. 
        
         
<P>As a part of the <CODE>add_frag</CODE> procedure, Mnesia will iterate
over all fragments corresponding to the <CODE>IterFrags</CODE> numbers
and invoke <CODE>key_to_frag_number(NewState,RecordKey)</CODE> for
each record. If the new fragment differs from the old
fragment, the record will be moved to the new fragment.
<P>As the <CODE>add_frag</CODE> 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 <CODE>IterFrags</CODE> and those corresponding to
<CODE>AdditionalLockFrags</CODE>.

</DIV>

<P><A NAME="del_frag/1"><STRONG><CODE>del_frag(State) -&#62; {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>IterFrags = [integer()]</CODE></STRONG><BR>
<STRONG><CODE>AdditionalLockFrags = [integer()]</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>NewState</CODE> will be stored as <CODE>hash_state</CODE> among the
other <CODE>frag_properties</CODE>. 
        
         
<P>As a part of the <CODE>del_frag</CODE> procedure, Mnesia will iterate
over all fragments corresponding to the <CODE>IterFrags</CODE> numbers
and invoke <CODE>key_to_frag_number(NewState,RecordKey)</CODE> for
each record. If the new fragment differs from the old
fragment, the record will be moved to the new fragment.
<P>Note that all records in the last fragment must be moved to
another fragment as the entire fragment will be deleted.
<P>As the <CODE>del_frag</CODE> 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 <CODE>IterFrags</CODE> and those corresponding to
<CODE>AdditionalLockFrags</CODE>.

</DIV>

<P><A NAME="key_to_frag_number/2"><STRONG><CODE>key_to_frag_number(State, Key) -&#62; FragNum | abort(Reason)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FragNum = integer()()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<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.
</DIV>

<P><A NAME="match_spec_to_frag_numbers/2"><STRONG><CODE>match_spec_to_frag_numbers(State, MatchSpec) -&#62; FragNums | abort(Reason)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>MatcSpec = ets_select_match_spec()</CODE></STRONG><BR>
<STRONG><CODE>FragNums = [FragNum]</CODE></STRONG><BR>
<STRONG><CODE>FragNum = integer()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<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.
</DIV>

<H3>See Also</H3>
<DIV CLASS=REFBODY>

<P> mnesia(3)


</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
 Hkan Mattsson - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>mnesia 4.3.3<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>