# Module gossip_cyclon

- Description
- Data Types
- Function Index
- Function Details

Gossip based membership management using CYCLON.

Copyright © 2008-2014 Zuse Institute Berlin

Version: $Id$

Behaviours: `gossip_beh`.

Authors: Christian Hennig (`hennig@zib.de`), Jens V. Fischer (`jensvfischer@gmail.com`).

References

- S. Voulgaris, D. Gavidia, M. van Steen. CYCLON: Inexpensive Membership Management for Unstructured P2P Overlays. Journal of Network and Systems Management, Vol. 13, No. 2, June 2005.

## Description

Gossip based membership management using CYCLON.

CYCLON provides an unstructured overlay which can be used to obtain the address of a random node from the entirety of all nodes. This is useful for instance for gossiping algorithms which need a random peers to communicate with.

The basic idea is as follows: Every node maintains cache of known peers. At the beginning of every cycle a random peer is chosen from the cache and a random subset of the node's neighbours is exchanged with that peer. The receiving peer uses the subset to update its own cache and also sends back a subset of its cache, which is merged with the cache of the initial peer. For details refer to the given paper.

## Data Types

### data()

    data() = cyclon_cache:cache()

### round()

    round() = non_neg_integer()

### state()

    state() =
        {Nodes :: cyclon_cache:cache(), MyNode :: node:node_type()}

the scalaris node of this process

## Function Index

check_config/0 |
fanout/0 | The fanout (in cyclon always 1).
get_subset_rand/1 | Sends a (local) message to the gossip module of the requesting process' group asking for a random subset of the stored nodes.
get_subset_rand/2 | Same as get_subset_rand/1 but sends the reply back to the given Pid.
get_subset_rand/3 | Same as get_subset_rand/2 but adds the given delay using msg_delay.
handle_msg/2 | Handle messages.
init/1 | Initiate the gossip_cyclon module.
integrate_data/3 | Integrate the received subset (at node P).
max_cycles_per_round/0 | The maximum number of cycles per round.
min_cycles_per_round/0 | The minimum number of cycles per round.
notify_change/3 | Notifies the module about changes.
rm_check/3 | Filter Function for subscribing to the rm loop.
rm_send_changes/5 | Exec Function for subscribing to the rm loop.
round_has_converged/1 | Always returns false, as cyclon does not implement rounds.
select_data/1 | Select and prepare the subset of the cache to be sent to the peer.
select_data_feeder/1 |
select_node/1 | Returns true, i.e.
select_reply_data/4 | Process the subset from the requestor (P) and select a subset as reply data (at Q).
shutdown/1 | Shut down the gossip_cyclon module.
trigger_interval/0 | The time interval in ms after which a new cycle is triggered by the gossip module.
web_debug_info/1 | Returns a key-value list of debug infos for the Web Interface.

## Function Details

### trigger_interval/0

    trigger_interval() -> pos_integer()

The time interval in ms after which a new cycle is triggered by the gossip module.

### fanout/0

    fanout() -> pos_integer()

The fanout (in cyclon always 1).

### min_cycles_per_round/0

    min_cycles_per_round() -> infinity

The minimum number of cycles per round. Returns infinity, as rounds are not implemented by cyclon.

### max_cycles_per_round/0

    max_cycles_per_round() -> infinity

The maximum number of cycles per round. Returns infinity, as rounds are not implemented by cyclon.

### check_config/0

    check_config() -> boolean()

### get_subset_rand/1

    get_subset_rand(N :: pos_integer()) -> ok

Sends a (local) message to the gossip module of the requesting process' group asking for a random subset of the stored nodes. The response in the form {cy_cache, [Node]} will be send (local) to the requesting process.

### get_subset_rand/2

    get_subset_rand(N :: pos_integer(), Pid :: comm:erl_local_pid()) ->
                       ok

Same as get_subset_rand/1 but sends the reply back to the given Pid.

### get_subset_rand/3

    get_subset_rand(N :: pos_integer(),
                    Pid :: comm:erl_local_pid(),
                    Delay :: non_neg_integer()) ->
                       ok

Same as get_subset_rand/2 but adds the given delay using msg_delay.

### init/1

    init(Args :: [proplists:property()]) -> {ok, state()}

Initiate the gossip_cyclon module.
Called by the gossip module upon startup.
The Instance information is ignored, {gossip_cyclon, default} is always used.

### select_node/1

    select_node(State :: state()) -> {true, state()}

Returns true, i.e. peer selection is done by gossip_cyclon module.

### select_data/1

    select_data(State :: state()) -> {ok | discard_msg, state()}

Select and prepare the subset of the cache to be sent to the peer.
Called by the gossip module at the beginning of every cycle.
The selected exchange data (i.e. the selected subset of the cache) is sent back to the gossip module as a message of the form {selected_data, Instance, ExchangeData}. gossip_trigger -> select_data() is equivalent to cy_shuffle in the old cyclon module.

### select_reply_data/4

    select_reply_data(PSubset :: data(),
                      Ref :: pos_integer(),
                      Round :: round(),
                      State :: state()) ->
                         {ok, state()}

Process the subset from the requestor (P) and select a subset as reply data (at Q).
Called by the behaviour module upon a p2p_exch message.
PSubset: exchange data (subset) from the p2p_exch request
Ref: used by the gossip module to identify the request
Round: ignored, as cyclon does not implement round handling p2p_exch msg -> seleft_reply_data() is equivalent to cy_subset msg in the old cyclon module.

### integrate_data/3

    integrate_data(QData :: {data(), data()},
                   Round :: round(),
                   State :: state()) ->
                      {ok, state()}

Integrate the received subset (at node P).
Called by the behaviour module upon a p2p_exch_reply message.
QData: the subset from the peer (QSubset) and the subset wich was sent in the request (PSubset)
Round: ignored, as cyclon does not implement round handling Upon finishing the processing of the data, a message of the form {integrated_data, Instance, RoundStatus} is to be sent to the gossip module. p2p_exch_reply msg -> integrate_data() is equivalent to the cy_subset_response msg in the old cyclon module.

### handle_msg/2

    handle_msg(Message, State :: state()) -> {ok, state()}

-     Message =
          {rm_changed, NewNode :: node:node_type()} |
          {get_ages, SourcePid :: comm:erl_local_pid()} |
          {get_subset_rand,
           N :: pos_integer(),
           SourcePid :: comm:erl_local_pid()} |
          {get_node_details_response, node_details:node_details()} |
          {get_dht_nodes_response, Nodes :: [comm:mypid()]}

Handle messages

### round_has_converged/1

    round_has_converged(State :: state()) -> {false, state()}

Always returns false, as cyclon does not implement rounds.

### notify_change/3

    notify_change(X1 :: any(), X2 :: any(), State :: state()) ->
                     {ok, state()}

Notifies the module about changes.
Changes can be new rounds, leadership changes or exchange failures. All of them are ignored, as cyclon doesn't use / implements this features.

### web_debug_info/1

    web_debug_info(State :: state()) ->
                      {KeyValueList ::
                           [{Key :: string(), Value :: string()}, ...],
                       state()}

Returns a key-value list of debug infos for the Web Interface.
Called by the gossip module upon {web_debug_info} messages.

### shutdown/1

    shutdown(State :: state()) -> {ok, shutdown}

Shut down the gossip_cyclon module.
Called by the gossip module upon stop_gossip_task(CBModule).

### rm_check/3

    rm_check(Neighbors, Neighbors, Reason) -> boolean()

-     Neighbors = nodelist:neighborhood()

-     Reason = rm_loop:reason()

Filter Function for subscribing to the rm loop

### rm_send_changes/5

    rm_send_changes(Pid :: pid(),
                    Tag :: cyclon,
                    OldNeighbors :: nodelist:neighborhood(),
                    NewNeighbors :: nodelist:neighborhood(),
                    Reason :: rm_loop:reason()) ->
                       ok

Exec Function for subscribing to the rm loop. Sends changes to a subscribed cyclon process when the neighborhood changes.

### select_data_feeder/1

    select_data_feeder(State :: state()) -> {state()}

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