# Module cyclon_cache

- Description
- Data Types
- Function Index
- Function Details

Cyclon node cache implementation using a list.

Copyright © 2008-2011 Zuse Institute Berlin

Version: $Id$

Authors: Christian Hennig (`hennig@zib.de`).

## Description

Cyclon node cache implementation using a list.

## Data Types

### age()

    age() = non_neg_integer()

### cache()

    cache() = [element()]

### element()

    element() = {node:node_type(), age()}

## Function Index

add_node/3 | Adds the given node to the cache or updates its age in the Cache if present.
debug_format_by_age/1 | Returns a list of keys (ages) and string values (nodes) for debug output used in the web interface.
get_ages/1 | Returns the ages of all nodes in the cache.
get_nodes/1 | Returns all nodes in the cache (without their ages).
get_random_nodes/2 | Returns a random subset of N nodes from the cache.
get_random_subset/2 | Returns a random subset of N elements from the cache.
inc_age/1 | Increases the age of every element in the cache by 1.
merge/5 | Merges MyCache at node MyNode with the ReceivedCache from another node to whom SendCache has been send.
new/0 | Creates a new and empty node cache.
new/2 | Creates a new node cache with the given two nodes and ages 0.
pop_oldest_node/1 | Finds the oldest element (randomized if multiple oldest elements) and removes it from the cache returning the new cache and this node.
pop_random_node/1 | Removes a random element from the (non-empty!) cache and returns the resulting cache and the removed node.
remove_node/2 | Removes any element with the given Node from the Cache.
size/1 | Counts the number of Cache entries.
trim/2 | Trims the cache to size TargetSize (if necessary) by deleting random entries as long as the cache is larger than the given TargetSize.

## Function Details

### new/0

    new() -> cache()

Creates a new and empty node cache.

### new/2

    new(Node1 :: node:node_type(), Node2 :: node:node_type()) ->
           cache()

Creates a new node cache with the given two nodes and ages 0.

### size/1

    size(Cache :: cache()) -> non_neg_integer()

Counts the number of Cache entries.

### pop_random_node/1

    pop_random_node(Cache :: [Cache :: element(), ...]) ->
                       {NewCache :: cache(),
                        PoppedNode :: node:node_type()}

Removes a random element from the (non-empty!) cache and returns the resulting cache and the removed node.

### get_random_subset/2

    get_random_subset(N :: non_neg_integer(), Cache :: cache()) ->
                         RandomSubset :: cache()

Returns a random subset of N elements from the cache.

### get_random_nodes/2

    get_random_nodes(N :: non_neg_integer(), Cache :: cache()) ->
                        Nodes :: [node:node_type()]

Returns a random subset of N nodes from the cache.

### pop_oldest_node/1

    pop_oldest_node(Cache :: cache()) ->
                       {NewCache :: cache(),
                        PoppedNode :: node:node_type()}

Finds the oldest element (randomized if multiple oldest elements) and removes it from the cache returning the new cache and this node.

### inc_age/1

    inc_age(Cache :: cache()) -> NewCache :: cache()

Increases the age of every element in the cache by 1.

### get_ages/1

    get_ages(Cache :: cache()) -> Ages :: [age()]

Returns the ages of all nodes in the cache.

### get_nodes/1

    get_nodes(Cache :: cache()) -> Nodes :: [node:node_type()]

Returns all nodes in the cache (without their ages).

### merge/5

    merge(MyCache :: cache(),
          MyNode :: node:node_type(),
          ReceivedCache :: cache(),
          SendCache :: cache(),
          TargetSize :: pos_integer()) ->
             NewCache :: cache()

Merges MyCache at node MyNode with the ReceivedCache from another node to whom SendCache has been send. The final cache size will not extend TargetSize. This will discard received entries pointing at MyNode and entries already contained in MyCache, fill up empty slots in the cache with received entries and further replace elements in MyCache using replace/5.

### add_node/3

    add_node(Node :: node:node_type(), Age :: age(), Cache :: cache()) ->
                NewCache :: cache()

Adds the given node to the cache or updates its age in the Cache if present. Beware: the node will be added to the cache no matter what size it already has!

### remove_node/2

    remove_node(Node :: node:node_type(), Cache :: cache()) ->
                   NewCache :: cache()

Removes any element with the given Node from the Cache.

### trim/2

    trim(Cache :: cache(), TargetSize :: pos_integer()) ->
            NewCache :: cache()

Trims the cache to size TargetSize (if necessary) by deleting random entries as long as the cache is larger than the given TargetSize.

### debug_format_by_age/1

    debug_format_by_age(Cache :: cache()) ->
                           KeyValueList ::
                               [{Age :: string(), Node :: string()}]

Returns a list of keys (ages) and string values (nodes) for debug output used in the web interface.

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