NAME

       mnesia_frag_hash - Defines mnesia_frag_hash callback behaviour

DESCRIPTION

       The  module  mnesia_frag_hash defines a callback behaviour for user defined hash functions
       of fragmented tables.

       Which module that is selected to implement the mnesia_frag_hash behaviour for a particular
       fragmented  table  is  specified  together with the other frag_properties. The hash_module
       defines the module name. The hash_state defines the initial hash state.

       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

EXPORTS

       init_state(Tab, State) -> NewState | abort(Reason)

              Types:

                 Tab = atom()
                 State = term()
                 NewState = term()
                 Reason = term()

              This   function   is   invoked   when   a   fragmented   table   is   created  with
              mnesia:create_table/2 or when a normal (un-fragmented) table is converted to  be  a
              fragmented table with mnesia:change_table_frag/2.

              Note that the add_frag/2 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.

              State is the initial value of the hash_state frag_property. The  NewState  will  be
              stored as hash_state among the other frag_properties.

       add_frag(State) -> {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)

              Types:

                 State = term()
                 NewState = term()
                 IterFrags = [integer()]
                 AdditionalLockFrags = [integer()]
                 Reason = term()

              In  order  to  scale  well,  it  is  a good idea ensure that the records are evenly
              distributed over all fragments including the new one.

              The NewState will be stored as hash_state among the other frag_properties.

              As a part of the  add_frag  procedure,  Mnesia  will  iterate  over  all  fragments
              corresponding       to       the       IterFrags       numbers      and      invoke
              key_to_frag_number(NewState,RecordKey) for each record. If the new fragment differs
              from the old fragment, the record will be moved to the new fragment.

              As  the  add_frag 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
              IterFrags and those corresponding to AdditionalLockFrags.

       del_frag(State) -> {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)

              Types:

                 State = term()
                 NewState = term()
                 IterFrags = [integer()]
                 AdditionalLockFrags = [integer()]
                 Reason = term()

              The NewState will be stored as hash_state among the other frag_properties.

              As  a  part  of  the  del_frag  procedure,  Mnesia  will iterate over all fragments
              corresponding      to      the       IterFrags       numbers       and       invoke
              key_to_frag_number(NewState,RecordKey) for each record. If the new fragment differs
              from the old fragment, the record will be moved to the new fragment.

              Note that all records in the last fragment must be moved to another fragment as the
              entire fragment will be deleted.

              As  the  del_frag 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
              IterFrags and those corresponding to AdditionalLockFrags.

       key_to_frag_number(State, Key) -> FragNum | abort(Reason)

              Types:

                 FragNum = integer()()
                 Reason = term()

              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.

       match_spec_to_frag_numbers(State, MatchSpec) -> FragNums | abort(Reason)

              Types:

                 MatcSpec = ets_select_match_spec()
                 FragNums = [FragNum]
                 FragNum = integer()
                 Reason = term()

              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.

SEE ALSO

       mnesia(3erl)