# Module rm_loop

- Description
- Data Types
- Function Index
- Function Details

Shared process for the ring maintenance implementations.

Copyright © 2010-2011 Zuse Institute Berlin

Version: $Id$

Authors: Nico Kruber (`kruber@zib.de`).

## Description

Shared process for the ring maintenance implementations.

## Data Types

### message()

    message() =
        {rm, trigger} |
        {rm, trigger_action} |
        {rm, notify_new_pred, NewPred :: node:node_type()} |
        {rm, notify_new_succ, NewSucc :: node:node_type()} |
        {rm, notify_slide_finished, SlideType :: pred | succ} |
        {rm,
         propose_new_neighbors,
         NewNodes :: [node:node_type(), ...]} |
        {rm,
         node_info,
         SourcePid :: comm:mypid(),
         Which ::
             [is_leaving | succlist | succ | predlist | pred | node,
              ...]} |
        {rm, leave, Tag :: jump | leave} |
        {rm, update_my_id, NewId :: rt_chord:key()} |
        {web_debug_info, Requestor :: comm:erl_local_pid()} |
        {rm,
         subscribe,
         Pid :: pid(),
         Tag :: any(),
         subscriber_filter_fun(),
         subscriber_exec_fun(),
         MaxCalls :: pos_integer() | inf} |
        {rm, unsubscribe, Pid :: pid(), Tag :: any()} |
        {rm, get_move_state, Pid :: pid()}

### reason()

    reason() =
        {slide_finished, pred | succ | none} |
        {graceful_leave, Node :: node:node_type()} |
        {node_crashed, Node :: comm:mypid()} |
        {add_subscriber} |
        {node_discovery} |
        {update_id_failed} |
        {unknown}

### state()

abstract datatype: `state()`

### subscriber_exec_fun()

    subscriber_exec_fun() =
        fun((Subscriber :: pid() | null,
             Tag :: any(),
             OldNeighbors :: nodelist:neighborhood(),
             NewNeighbors :: nodelist:neighborhood(),
             Reason :: reason()) ->
                any())

### subscriber_filter_fun()

    subscriber_filter_fun() =
        fun((OldNeighbors :: nodelist:neighborhood(),
             NewNeighbors :: nodelist:neighborhood(),
             Reason :: reason()) ->
                boolean())

## Function Index

cleanup/1 | Cleans up before the state is deleted, e.g.
fd_notify/4 |
get_neighbors/1 | Returns the current neighborhood structure.
get_web_debug_info/1 |
has_left/1 | Returns whether the current node has already left the ring (intermediate state before the node is killed or jumping to another ID).
init/4 | Initializes the rm_loop state.
init_first/0 | Initializes the rm_loop trigger and whatever the RM-specific code wants.
is_responsible/2 | Convenience method checking whether the current node is responsible for the given key, i.e.
leave/1 | Notifies fd-subscribed nodes that the current dht_node is going to leave.
notify_new_pred/2 | Sends a message to the remote node's dht_node process notifying it of a new predecessor.
notify_new_succ/2 | Sends a message to the remote node's dht_node process notifying it of a new successor.
notify_slide_finished/1 | Sends a message to the local node's dht_node process notifying it of a finished slide.
on/2 | Message handler when the rm_loop module is fully initialized.
propose_new_neighbors/1 | Sends a message to the local node's dht_node process notifying it of a potential new neighbor.
send_trigger/0 | Starts the RM trigger.
subscribe/5 | Registers the given function to be called when the dht_node changes its id.
subscribe_dneighbor_change_filter/3 | Filter function for subscriptions that returns true if a direct neighbor, i.e.
subscribe_dneighbor_change_slide_filter/3 | Filter function for subscriptions that returns true if a direct neighbor, i.e.
unittest_create_state/2 | Creates a state() object for a unit test.
unsubscribe/2 | Un-registers the given process with the given tag from node change updates.
update_id/1 | Updates a dht node's id and sends the ring maintenance a message about the change.
zombie_node/2 |

## Function Details

### get_neighbors/1

    get_neighbors(X1 :: state()) -> nodelist:neighborhood()

Returns the current neighborhood structure.

### has_left/1

    has_left(X1 :: state()) -> boolean()

Returns whether the current node has already left the ring (intermediate state before the node is killed or jumping to another ID).

### is_responsible/2

    is_responsible(Key :: intervals:key(), X2 :: state()) -> boolean()

Convenience method checking whether the current node is responsible for the given key, i.e. has not left and Key is in range. Improves performance over two calls in dht_node_state/is_responsible/2.

### leave/1

    leave(Tag :: jump | leave) -> ok

Notifies fd-subscribed nodes that the current dht_node is going to leave. Will inform the dht_node process (message handled in dht_node_move). Note: only call this method from inside the dht_node process!

### notify_new_succ/2

    notify_new_succ(Node :: comm:mypid(), NewSucc :: node:node_type()) ->
                       ok

Sends a message to the remote node's dht_node process notifying it of a new successor.

### notify_new_pred/2

    notify_new_pred(Node :: comm:mypid(), NewPred :: node:node_type()) ->
                       ok

Sends a message to the remote node's dht_node process notifying it of a new predecessor.

### notify_slide_finished/1

    notify_slide_finished(SlideType :: pred | succ) -> ok

Sends a message to the local node's dht_node process notifying it of a finished slide.

### propose_new_neighbors/1

    propose_new_neighbors(NewNodes :: [node:node_type(), ...]) -> ok

Sends a message to the local node's dht_node process notifying it of a potential new neighbor.

### update_id/1

    update_id(NewId :: rt_chord:key()) -> ok

Updates a dht node's id and sends the ring maintenance a message about the change. Beware: the only allowed node id changes are between the node's predecessor and successor!

### subscribe_dneighbor_change_filter/3

    subscribe_dneighbor_change_filter(OldNeighbors ::
                                          nodelist:neighborhood(),
                                      NewNeighbors ::
                                          nodelist:neighborhood(),
                                      Reason :: reason()) ->
                                         boolean()

Filter function for subscriptions that returns true if a direct neighbor, i.e. pred, succ or base node, changed.

### subscribe_dneighbor_change_slide_filter/3

    subscribe_dneighbor_change_slide_filter(OldNeighbors ::
                                                nodelist:neighborhood(),
                                            NewNeighbors ::
                                                nodelist:neighborhood(),
                                            Reason :: reason()) ->
                                               boolean()

Filter function for subscriptions that returns true if a direct neighbor, i.e. pred, succ or base node, changed or a slide operation finished.

### subscribe/5

    subscribe(Pid :: pid() | null,
              Tag :: any(),
              FilterFun :: subscriber_filter_fun(),
              ExecFun :: subscriber_exec_fun(),
              MaxCalls :: pos_integer() | inf) ->
                 ok

Registers the given function to be called when the dht_node changes its id. It will get the given Pid and the new node as its parameters.

### unsubscribe/2

    unsubscribe(Pid :: pid() | null, Tag :: any()) -> ok

Un-registers the given process with the given tag from node change updates.

### send_trigger/0

    send_trigger() -> ok

Starts the RM trigger.

### init_first/0

    init_first() -> ok

Initializes the rm_loop trigger and whatever the RM-specific code wants. NOTE: this is called during dht_node:init/1 and thus is not infected with trace_mpath.

### init/4

    init(Me :: node:node_type(),
         Pred :: node:node_type(),
         Succ :: node:node_type(),
         OldSubscrTable :: null | ets:tid()) ->
            state()

Initializes the rm_loop state.

### cleanup/1

    cleanup(State :: state()) -> ok

Cleans up before the state is deleted, e.g. removes fd subscriptions for a rejoin operation. NOTE: only valid when HasLeft is set in the state!

### unittest_create_state/2

    unittest_create_state(Neighbors :: nodelist:neighborhood(),
                          HasLeft :: boolean()) ->
                             state()

Creates a state() object for a unit test. Pre: the process must have joined a group. See pid_groups:join_as/2.

### on/2

    on(Message :: message() | rm_tman:custom_message(),
       State :: state()) ->
          state()

Message handler when the rm_loop module is fully initialized.

### fd_notify/4

    fd_notify(State :: state(),
              Event :: fd:event(),
              DeadPid :: comm:mypid(),
              Data :: term()) ->
                 state()

### zombie_node/2

    zombie_node(State :: state(), Node :: node:node_type()) -> state()

### get_web_debug_info/1

    get_web_debug_info(State :: state()) -> [{string(), string()}]

Generated by EDoc, Apr 22 2017, 15:58:25.