# Module nodelist

- Description
- Data Types
- Function Index
- Function Details

Provides lists of nodes that are sorted by the nodes' ids.

Copyright © 2010-2014 Zuse Institute Berlin

Version: $Id$

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

## Description

Provides lists of nodes that are sorted by the nodes' ids.

## Data Types

### eval_fun()

    eval_fun() = fun((node:node_type()) -> any())

### filter_fun()

    filter_fun() = fun((node:node_type()) -> boolean())

### neighborhood()

abstract datatype: `neighborhood()`

### non_empty_snodelist()

    non_empty_snodelist() = [node:node_type(), ...]

non-empty (sorted) node list

### snodelist()

    snodelist() = [node:node_type()]

(sorted) node list

## Function Index

add_node/4 | Adds a node to a neighborhood structure and truncates the predecessor and successor list to the given sizes.
add_nodes/4 | Adds nodes from the given node list to the given neighborhood structure and truncates the predecessor and successor list to the given sizes.
create_pid_to_node_dict/2 | Creates a dictionary mapping a node PID to the newest version of its node object from the given lists.
filter/2 | Keeps any node for which FilterFun returns true in a neighborhood.
filter/3 | Keeps any node for which FilterFun returns true in a neighborhood and executes EvalFun for any other node.
filter_min_length/4 | Keeps any node for which FilterFun returns true in a predecessor and successor lists but produces a neighborhood with at least MinPredsLength predecessors and at least MinSuccsLength successors by adding enough unmatching nodes.
has_real_pred/1 | Returns whether the neighborhood contains a real predecessor (one not equal to the own node) or not (provided for convenience).
has_real_succ/1 | Returns whether the neighborhood contains a real predecessor (one not equal to the own node) or not (provided for convenience).
largest_smaller_than/2 | Returns the node among all know neighbors (including the base node) with the largest id smaller than Id.
largest_smaller_than/3 | Returns the node among all know neighbors (including the base node) with the largest id smaller than Id given that a previous search found LastFound as its Node with the largest id smaller than id.
lfilter/2 | Keeps any node for which FilterFun returns true in a node list.
lfilter/3 | Keeps any node for which FilterFun returns true in a node list and executes EvalFun for any other node.
lfilter_min_length/3 | Keeps any node for which FilterFun returns true in a node list but produces a node list with at least MinLength elements by adding enough unmatching nodes.
lremove/2 | Removes the given node (or node with the given Pid) from a node list (provided for convenience - see lfilter/2).
lremove/3 | Removes the given node (or node with the given Pid) from a node list and executes EvalFun for any such occurrence (provided for convenience - see filter/3).
lremove_outdated/1 | Removes any node with outdated ID information from the list as well as any invalid node.
lremove_outdated/2 | Removes any node with outdated ID information from the list as well as any outdated node that shares the same process as Node and any invalid node.
lupdate_ids/2 | Updates the node IDs of the nodes in both lists with the most up-to-date ID in any of the two lists.
merge/4 | Merges nodes of Neighbors2 into Neighbors1 and truncates the predecessor and successor lists to the given sizes.
mk_neighborhood/2 | Creates a neighborhood structure for the given node from a given (unsorted) node list.
mk_neighborhood/4 | Creates a neighborhood structure for the given node from a given (unsorted) node list and limits its predecessor and successor lists to the given sizes.
mk_nodelist/2 | Creates a sorted nodelist starting at the given node and going clockwise along the ring (also see succ_ord_node/3).
new_neighborhood/1 | Creates a new neighborhood structure for the given node.
new_neighborhood/2 | Creates a new neighborhood structure for the given node and a neighbor (this will be its predecessor and successor).
new_neighborhood/3 | Creates a new neighborhood structure for the given node, its predecessor and successor.
node/1 | Returns the neighborhood's node.
node_range/1 | Returns the node's range.
nodeid/1 | Returns the ID of the neighborhood's node (provided for convenience).
pred/1 | Returns a neighborhood's or a node lists's predecessor (may be the node itself).
preds/1 | Returns the neighborhood's predecessor list.
remove/2 | Removes the given node (or node with the given Pid) from a neighborhood (provided for convenience - see filter/2).
remove/3 | Removes the given node (or node with the given Pid) from a neighborhood and executes EvalFun for any such occurrence (provided for convenience, see filter/3).
succ/1 | Returns the neighborhood's or a node lists's successor (may be the node itself).
succ_ord_id/2 | Defines that K1 is less than or equal to K2 if their IDs are.
succ_ord_id/3 | Defines a 'less than or equal' order starting from a base node going along the ring towards the successor where nodes that are further away are said to be larger than nodes with smaller distances.
succ_ord_node/2 | Defines that N1 is less than or equal to N2 if their IDs are (provided for convenience).
succ_ord_node/3 | Defines a 'less than or equal' order starting from a base node going along the ring towards the successor where nodes that are further away are said to be larger than nodes with smaller distances.
succ_range/1 | Returns the successor's range.
succs/1 | Returns the neighborhood's successor list.
to_list/1 | Converts a neighborhood to a sorted list of nodes including the predecessors, the node and its successors.
trunc/3 | Truncates the given neighborhood's predecessor and successor lists to the given sizes.
trunc_preds/2 | Truncates the given neighborhood's predecessor list to the given size.
trunc_succs/2 | Truncates the given neighborhood's successor list to the given size.
update_ids/2 | Updates the node IDs of the nodes in the neighborhood with the most up-to-date ID in either its own lists or the given node list.
update_node/2 | Updates the base node of the neighborhood if its ID is still between the ID of the predecessor and successor.

## Function Details

### new_neighborhood/1

    new_neighborhood(Node :: node:node_type()) -> neighborhood()

Creates a new neighborhood structure for the given node.

### new_neighborhood/2

    new_neighborhood(Node :: node:node_type(),
                     Neighbor :: node:node_type()) ->
                        neighborhood()

Creates a new neighborhood structure for the given node and a neighbor (this will be its predecessor and successor).

### new_neighborhood/3

    new_neighborhood(Pred :: node:node_type(),
                     Node :: node:node_type(),
                     Succ :: node:node_type()) ->
                        neighborhood()

Creates a new neighborhood structure for the given node, its predecessor and successor. If the order is wrong, Pred and Succ will be exchanged. (provided for convenience - special case of mk_neighborhood)

### trunc/3

    trunc(Neighborhood :: neighborhood(),
          PredsLength :: pos_integer(),
          SuccsLength :: pos_integer()) ->
             neighborhood()

Truncates the given neighborhood's predecessor and successor lists to the given sizes.

### trunc_preds/2

    trunc_preds(X1 :: neighborhood(), PredsLength :: pos_integer()) ->
                   neighborhood()

Truncates the given neighborhood's predecessor list to the given size.

### trunc_succs/2

    trunc_succs(X1 :: neighborhood(), SuccsLength :: pos_integer()) ->
                   neighborhood()

Truncates the given neighborhood's successor list to the given size.

### node/1

    node(Neighborhood :: neighborhood()) -> node:node_type()

Returns the neighborhood's node.

### nodeid/1

    nodeid(Neighborhood :: neighborhood()) -> rt_chord:key()

Returns the ID of the neighborhood's node (provided for convenience).

### node_range/1

    node_range(Neighborhood :: neighborhood()) -> intervals:interval()

Returns the node's range.

### update_node/2

    update_node(X1 :: neighborhood(), NewBaseNode :: node:node_type()) ->
                   neighborhood()

Updates the base node of the neighborhood if its ID is still between the ID of the predecessor and successor. Otherwise throws an exception. Note: pred and/or succ could change due to (outdated) other preds/succs.

### preds/1

    preds(Neighborhood :: neighborhood()) -> non_empty_snodelist()

Returns the neighborhood's predecessor list.

### pred/1

    pred(Neighborhood :: neighborhood()) -> node:node_type()

Returns a neighborhood's or a node lists's predecessor (may be the node itself).

### has_real_pred/1

    has_real_pred(Neighborhood :: neighborhood()) -> boolean()

Returns whether the neighborhood contains a real predecessor (one not equal to the own node) or not (provided for convenience).

### succs/1

    succs(Neighborhood :: neighborhood()) -> non_empty_snodelist()

Returns the neighborhood's successor list.

### succ/1

    succ(Neighborhood :: neighborhood()) -> node:node_type()

Returns the neighborhood's or a node lists's successor (may be the node itself).

### succ_range/1

    succ_range(Neighborhood :: neighborhood()) -> intervals:interval()

Returns the successor's range.

### has_real_succ/1

    has_real_succ(Neighborhood :: neighborhood()) -> boolean()

Returns whether the neighborhood contains a real predecessor (one not equal to the own node) or not (provided for convenience).

### mk_nodelist/2

    mk_nodelist(UnorderedNodeList :: [node:node_type()],
                Node :: node:node_type()) ->
                   OrderedNodeList :: snodelist()

Creates a sorted nodelist starting at the given node and going clockwise along the ring (also see succ_ord_node/3).

### mk_neighborhood/4

    mk_neighborhood(NodeList :: [node:node_type()],
                    Node :: node:node_type(),
                    PredsLength :: pos_integer(),
                    SuccsLength :: pos_integer()) ->
                       neighborhood()

Creates a neighborhood structure for the given node from a given (unsorted) node list and limits its predecessor and successor lists to the given sizes.

### mk_neighborhood/2

    mk_neighborhood(NodeList :: [node:node_type()],
                    Node :: node:node_type()) ->
                       neighborhood()

Creates a neighborhood structure for the given node from a given (unsorted) node list. Note that in this case, the predecessor and successor lists will effectively be the same!

### lremove/2

    lremove(NodeOrPid :: node:node_type() | comm:mypid() | pid(),
            NodeList :: snodelist()) ->
               snodelist()

Removes the given node (or node with the given Pid) from a node list (provided for convenience - see lfilter/2).

### remove/2

    remove(NodeOrPid :: node:node_type() | comm:mypid() | pid(),
           Neighborhood :: neighborhood()) ->
              neighborhood()

Removes the given node (or node with the given Pid) from a neighborhood (provided for convenience - see filter/2). Note: A neighborhood's base node is never removed!

### lremove/3

    lremove(NodeOrPid :: node:node_type() | comm:mypid() | pid(),
            NodeList :: snodelist(),
            EvalFun :: eval_fun()) ->
               snodelist()

Removes the given node (or node with the given Pid) from a node list and executes EvalFun for any such occurrence (provided for convenience - see filter/3).

### remove/3

    remove(NodeOrPid :: node:node_type() | comm:mypid() | pid(),
           Neighborhood :: neighborhood(),
           EvalFun :: eval_fun()) ->
              neighborhood()

Removes the given node (or node with the given Pid) from a neighborhood and executes EvalFun for any such occurrence (provided for convenience, see filter/3). Note: A neighborhood's base node is never removed!

### lfilter/2

    lfilter(NodeList :: snodelist(), FilterFun :: filter_fun()) ->
               snodelist()

Keeps any node for which FilterFun returns true in a node list.

### filter/2

    filter(X1 :: neighborhood(), FilterFun :: filter_fun()) ->
              neighborhood()

Keeps any node for which FilterFun returns true in a neighborhood. Note: A neighborhood's base node is never removed!

### lfilter/3

    lfilter(Rest :: snodelist(),
            FilterFun :: filter_fun(),
            EvalFun :: eval_fun()) ->
               snodelist()

Keeps any node for which FilterFun returns true in a node list and executes EvalFun for any other node.

### filter/3

    filter(X1 :: neighborhood(),
           FilterFun :: filter_fun(),
           EvalFun :: eval_fun()) ->
              neighborhood()

Keeps any node for which FilterFun returns true in a neighborhood and executes EvalFun for any other node. Note: A neighborhood's base node is never removed!

### lfilter_min_length/3

    lfilter_min_length(NodeList :: snodelist(),
                       FilterFun :: filter_fun(),
                       MinLength :: non_neg_integer()) ->
                          snodelist()

Keeps any node for which FilterFun returns true in a node list but produces a node list with at least MinLength elements by adding enough unmatching nodes. Preserves the order of the list.

### filter_min_length/4

    filter_min_length(X1 :: neighborhood(),
                      FilterFun :: filter_fun(),
                      MinPredsLength :: non_neg_integer(),
                      MinSuccsLength :: non_neg_integer()) ->
                         neighborhood()

Keeps any node for which FilterFun returns true in a predecessor and successor lists but produces a neighborhood with at least MinPredsLength predecessors and at least MinSuccsLength successors by adding enough unmatching nodes. If the predecessor or successor list is smaller than MinPredsLength and MinSuccsLength respectively, the whole list will be used. Note: A neighborhood's base node is never removed!

### to_list/1

    to_list(X1 :: neighborhood()) -> non_empty_snodelist()

Converts a neighborhood to a sorted list of nodes including the predecessors, the node and its successors. The first element of the resulting list will be the node itself, afterwards every known node along the ring towards the first node.

### merge/4

    merge(Neighbors1 :: neighborhood(),
          Neighbors2 :: neighborhood(),
          PredsLength :: pos_integer(),
          SuccsLength :: pos_integer()) ->
             neighborhood()

Merges nodes of Neighbors2 into Neighbors1 and truncates the predecessor and successor lists to the given sizes.

### add_node/4

    add_node(Neighbors :: neighborhood(),
             NodeToAdd :: node:node_type(),
             PredsLength :: pos_integer(),
             SuccsLength :: pos_integer()) ->
                neighborhood()

Adds a node to a neighborhood structure and truncates the predecessor and successor list to the given sizes. Note: nodes which have only been present in the predecessor (successor) list may now also appear in the successor (predecessor) list if a list has been too small.

### add_nodes/4

    add_nodes(Neighbors :: neighborhood(),
              NodeList :: [node:node_type()],
              PredsLength :: pos_integer(),
              SuccsLength :: pos_integer()) ->
                 neighborhood()

Adds nodes from the given node list to the given neighborhood structure and truncates the predecessor and successor list to the given sizes. Note: nodes which have only been present in the predecessor (successor) list may now also appear in the successor (predecessor) list if a list has been too small.

### update_ids/2

    update_ids(Neighbors :: neighborhood(),
               NodeList :: [node:node_type()]) ->
                  neighborhood()

Updates the node IDs of the nodes in the neighborhood with the most up-to-date ID in either its own lists or the given node list. Note: throws if any node in the NodeList is the same as the base node but with an updated ID!

### succ_ord_node/2

    succ_ord_node(N1 :: node:node_type(), N2 :: node:node_type()) ->
                     boolean()

Defines that N1 is less than or equal to N2 if their IDs are (provided for convenience).

### succ_ord_id/2

    succ_ord_id(K1 :: rt_chord:key(), K2 :: rt_chord:key()) ->
                   boolean()

Defines that K1 is less than or equal to K2 if their IDs are.

### succ_ord_node/3

    succ_ord_node(N1 :: node:node_type(),
                  N2 :: node:node_type(),
                  BaseNode :: node:node_type()) ->
                     boolean()

Defines a 'less than or equal' order starting from a base node going along the ring towards the successor where nodes that are further away are said to be larger than nodes with smaller distances.

### succ_ord_id/3

    succ_ord_id(K1 :: rt_chord:key(),
                K2 :: rt_chord:key(),
                BaseKey :: rt_chord:key()) ->
                   boolean()

Defines a 'less than or equal' order starting from a base node going along the ring towards the successor where nodes that are further away are said to be larger than nodes with smaller distances.

### create_pid_to_node_dict/2

    create_pid_to_node_dict(Dict, NodeLists :: [[node:node_type()]]) ->
                               Dict

-     Dict = dict:dict(comm:mypid(), node:node_type())

Creates a dictionary mapping a node PID to the newest version of its node object from the given lists.

### lremove_outdated/2

    lremove_outdated(NodeList :: [node:node_type()],
                     Node :: node:node_type() | null) ->
                        [node:node_type()]

Removes any node with outdated ID information from the list as well as any outdated node that shares the same process as Node and any invalid node.

### lremove_outdated/1

    lremove_outdated(NodeList :: [node:node_type()]) ->
                        [node:node_type()]

Removes any node with outdated ID information from the list as well as any invalid node.

### lupdate_ids/2

    lupdate_ids(L1 :: [node:node_type()], L2 :: [node:node_type()]) ->
                   {L1Upd :: [node:node_type()],
                    L2Upd :: [node:node_type()]}

Updates the node IDs of the nodes in both lists with the most up-to-date ID in any of the two lists. The returned lists are in the same order as as the input lists and may now contain duplicates (we could not decide which to remove here!). Note that due to the updated IDs the order might not be correct, i.e. according to some ordering function, anymore!

### largest_smaller_than/2

    largest_smaller_than(Neighbors :: neighborhood(),
                         Id :: rt_chord:key()) ->
                            node:node_type() | null

Returns the node among all know neighbors (including the base node) with the largest id smaller than Id.

### largest_smaller_than/3

    largest_smaller_than(Neighbors :: neighborhood(),
                         Id :: rt_chord:key(),
                         LastFound :: node:node_type()) ->
                            node:node_type()

Returns the node among all know neighbors (including the base node) with the largest id smaller than Id given that a previous search found LastFound as its Node with the largest id smaller than id.

Generated by EDoc, Feb 29 2016, 16:12:18.