# Various wrappers for DHT logics module

**Author(s):**Arsen Kostenko.

This module contains miscellaneous predicates related to the `dht_logic.pl` module. Mostly various calculation-wrappers.

## Usage and interface

**Library usage:**`:- use_module(library(dht_logic_misc)).`**Exports:****Other modules used:***System library modules:*`indexer/hash`,`dht/dht_config`.

## Documentation on exports

PREDICATE

This predicate calculates

`(2**m)`, where 'm' is equal to`hash_power/1`received from system wide configurations stored in`dht_config.pl`.**Usage:** `hash_size(Size)`

*Description:*The only purpose of`hash_size/1`predicate is to get corresponding value from system wide configurations stored in`dht_config.pl`file and convert it into the number of nodes virtually available in the current DHT installation.*The following properties should hold at call time:*

(term_typing:var/1)Size is a free variable.*The following properties should hold upon exit:*

(basic_props:gnd/1)Size is ground.

(basic_props:int/1)Size is an integer.

PREDICATE

This predicate calculates

`(2**m)-1`, where 'm' is equal to`hash_power/1`received from system wide configurations stored in`dht_config.pl`.**Usage 1:** `highest_hash_number(N)`

*Description:*If used with a ground argument`highest_hash_number/1`simply checks whether the value supplied corresponds to the biggest hash number possible in the DHT.*The following properties should hold at call time:*

(basic_props:int/1)N is an integer.

**Usage 2:** `highest_hash_number(N)`

*Description:*Otherwise (if argument happens to be a free variable) the value of N is bound to the highest hash number possible in the DHT.*The following properties should hold at call time:*

(term_typing:var/1)N is a free variable.*The following properties should hold upon exit:*

(basic_props:int/1)N is an integer.

PREDICATE

This kind of computation is usually performed every time, when one needs to get value of hash-function.

**Usage:** `consistent_hash(Term,DHTHash)`

*Description:*Straightforward computation of hash (DHTHash) on the basis of Term supplied.*The following properties should hold at call time:*

(basic_props:term/1)Term is any term.

(term_typing:var/1)DHTHash is a free variable.*The following properties should hold upon exit:*

(basic_props:term/1)Term is any term.

(basic_props:int/1)DHTHash is an integer.

PREDICATE

Performs the calculation of

`(id+1) mod ((2**m)-1)`, where`id`is the first argument supplied, and`m`is equal to`hash_power/1`.**Usage:** `next_on_circle(Id,Num)`

*Description:*`next_on_circle/2`is a calculation wrapping. One can only use it with first argument ground and equal to integer value. What is more, that value**MUST**be kept within certain bounds: value of Id**MUST**meet the constraints 0<=Id<=HighNum, where HighNum is retrieved via`highest_hash_number/1`predicate.*The following properties should hold at call time:*

(basic_props:int/1)Id is an integer.

(term_typing:var/1)Num is a free variable.*The following properties should hold upon exit:*

(basic_props:int/1)Id is an integer.

(basic_props:int/1)Num is an integer.

PREDICATE

`not_in_circle_oc/3`: the 'oc' suffix stands for "open-closed" interval. The predicate implements the behavior of the expression:

`Id not_in (a,b]`. where both 'a' and 'b' are numbers/identifiers on the DHT-ring.

**Usage:** `not_in_circle_oc(Id,Start,End)`

*Description:*Yet another wrapper around simple calculations. All arguments are expected to be ground, by the time the predicate is called. The predicate checks whether the value supplied as Id fits into circle sector defined by values of Start and End. If the condition is not true - the whole predicate fails.*The following properties should hold at call time:*

(basic_props:int/1)Id is an integer.

(basic_props:int/1)Start is an integer.

(basic_props:int/1)End is an integer.

PREDICATE

`in_circle_oo/3`: the 'oo' suffix stands for "open-open" circle interval. The predicate implements the behavior of following expression:

`Id in (a,b)`.

**Usage:** `in_circle_oo(Id,Start,End)`

*Description:*Check whether value of Id fits into sector defined by Start and End excluding both, fail otherwise.*The following properties should hold at call time:*

(basic_props:int/1)Id is an integer.

(basic_props:int/1)Start is an integer.

(basic_props:int/1)End is an integer.

PREDICATE

`in_circle_oc/3`: the 'oc' suffix stands for "open-closed" interval. The predicate is based on

`in_circle_oo/3`and considers the interval to be closed on the right. This predicate implements the behavior of the expression:

`Id in (a,b]`

**Usage:** `in_circle_oc(Id,Start,End)`

*Description:*Check whether value of Id fits into sector defined by Start and End excluding first and including second. Fail if the condition does not hold.*The following properties should hold at call time:*

(basic_props:int/1)Id is an integer.

(basic_props:int/1)Start is an integer.

(basic_props:int/1)End is an integer.