NAME

       mnesia_frag_hash - Defines mnesia_frag_hash callback behavior

DESCRIPTION

       This module defines a callback behavior for user-defined hash functions of fragmented tables.

       Which  module  that  is  selected  to implement the mnesia_frag_hash behavior 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.

       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.

EXPORTS

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

              Types:

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

              Starts when a fragmented table is created with the function mnesia:create_table/2 or when a normal
              (unfragmented) table is converted to be a fragmented table with mnesia:change_table_frag/2.

              Notice  that  the  function add_frag/2 is started one time for each of the other fragments (except
              number 1) as a part of the table creation procedure.

              State is the initial value of the hash_state frag_property. NewState is 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()

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

              NewState is stored as hash_state among the other frag_properties.

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

              As the add_frag procedure is a part of a schema transaction, Mnesia acquires 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()

              NewState is stored as hash_state among the other frag_properties.

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

              Notice that all records in the last fragment must be moved to  another  fragment,  as  the  entire
              fragment is deleted.

              As  the  del_frag  procedure is a part of a schema transaction, Mnesia acquires 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()

              Starts  whenever  Mnesia  needs  to  determine  which  fragment a certain record belongs to. It is
              typically started 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 called whenever Mnesia needs  to  determine  which  fragments  that  need  to  be
              searched for a MatchSpec. It is typically called by select and match_object.

SEE ALSO

       mnesia(3erl)