# Module api_tx

- Description
- Data Types
- Function Index
- Function Details

API for transactional access to replicated DHT items.

Copyright © 2011, 2012 Zuse Institute Berlin

Version: $Id$

Authors: Florian Schintke (`schintke@zib.de`), Nico Kruber (`kruber@zib.de`).

## Description

API for transactional access to replicated DHT items. For single request/single item operations, we provide read/1, write/2, test_and_set/3, add_on_nr/2 and add_del_on_list/3 functions that directly commit.

For compound transactions a transaction log has to be passed through all operations and finally has to be committed. This is supported by the functions new_tlog/0, read/2, write/3, req_list/2, and commit/1.

## Data Types

### add_del_on_list_request()

    add_del_on_list_request() =
        {add_del_on_list,
         client_key(),
         client_value(),
         client_value()}

### add_del_on_list_request_enc()

    add_del_on_list_request_enc() =
        {add_del_on_list,
         client_key(),
         rdht_tx:encoded_value(),
         rdht_tx:encoded_value()}

### add_on_nr_request()

    add_on_nr_request() = {add_on_nr, client_key(), client_value()}

### add_on_nr_request_enc()

    add_on_nr_request_enc() =
        {add_on_nr, client_key(), rdht_tx:encoded_value()}

### client_key()

    client_key() = [unicode_char()]

### client_value()

    client_value() = any()

### commit_result()

    commit_result() = {ok} | {fail, abort, [client_key()]}

### listop_result()

    listop_result() = write_result() | {fail, not_a_list}

### numberop_result()

    numberop_result() = write_result() | {fail, not_a_number}

### read_random_from_list_request()

    read_random_from_list_request() =
        {read, client_key(), random_from_list}

### read_random_from_list_result()

    read_random_from_list_result() =
        {ok, RandomValue_ListLen_MaybeEncoded :: client_value()} |
        {fail, not_found | empty_list | not_a_list}

### read_request()

    read_request() = {read, client_key()}

### read_result()

    read_result() = {ok, client_value()} | {fail, not_found}

### read_sublist_request()

    read_sublist_request() =
        {read,
         client_key(),
         {sublist,
          Start :: pos_integer() | neg_integer(),
          Len :: integer()}}

### read_sublist_result()

    read_sublist_result() =
        {ok, SubList_ListLen_MaybeEncoded :: client_value()} |
        {fail, not_found | not_a_list}

### request()

    request() = request_on_key() | {commit}

### request_enc()

    request_enc() = request_on_key_enc() | {commit}

### request_on_key()

    request_on_key() =
        read_request() |
        read_random_from_list_request() |
        read_sublist_request() |
        write_request() |
        add_del_on_list_request() |
        add_on_nr_request() |
        test_and_set_request()

### request_on_key_enc()

    request_on_key_enc() =
        read_request() |
        read_random_from_list_request() |
        read_sublist_request() |
        write_request_enc() |
        add_del_on_list_request_enc() |
        add_on_nr_request_enc() |
        test_and_set_request_enc()

### result()

    result() =
        read_result() |
        read_random_from_list_result() |
        read_sublist_result() |
        write_result() |
        listop_result() |
        numberop_result() |
        testandset_result() |
        commit_result()

### test_and_set_request()

    test_and_set_request() =
        {test_and_set,
         client_key(),
         Old :: client_value(),
         New :: client_value()}

### test_and_set_request_enc()

    test_and_set_request_enc() =
        {test_and_set,
         client_key(),
         Old :: rdht_tx:encoded_value(),
         New :: rdht_tx:encoded_value()}

### testandset_result()

    testandset_result() =
        write_result() |
        {fail,
         not_found | {key_changed, RealOldValue :: client_value()}}

### unicode_char()

    unicode_char() = 0..55295 | 57344..65533 | 65536..1114111

### write_request()

    write_request() = {write, client_key(), client_value()}

### write_request_enc()

    write_request_enc() =
        {write, client_key(), rdht_tx:encoded_value()}

### write_result()

    write_result() = {ok}

## Function Index

add_del_on_list/3 |
add_del_on_list/4 |
add_on_nr/2 |
add_on_nr/3 |
commit/1 |
get_system_snapshot/0 |
new_tlog/0 |
read/1 |
read/2 |
req_list/1 |
req_list/2 | Perform several requests inside a transaction and monitors its execution time.
req_list_commit_each/1 |
test_and_set/3 |
test_and_set/4 |
write/2 |
write/3 |

## Function Details

### new_tlog/0

    new_tlog() -> tx_tlog:tlog_ext()

### req_list/1

    req_list(ReqList :: [request()]) ->
                {tx_tlog:tlog_ext(), [result()]}

### read/2

    read(TLog :: tx_tlog:tlog_ext(), Key :: client_key()) ->
            {tx_tlog:tlog_ext(), read_result()}

### write/3

    write(TLog :: tx_tlog:tlog_ext(),
          Key :: client_key(),
          Value :: client_value()) ->
             {tx_tlog:tlog_ext(), write_result()}

### add_del_on_list/4

    add_del_on_list(TLog :: tx_tlog:tlog_ext(),
                    Key :: client_key(),
                    ToAdd :: [client_value()],
                    ToRemove :: [client_value()]) ->
                       {tx_tlog:tlog_ext(), listop_result()}

### add_on_nr/3

    add_on_nr(TLog :: tx_tlog:tlog_ext(),
              Key :: client_key(),
              ToAdd :: number()) ->
                 {tx_tlog:tlog_ext(), numberop_result()}

### test_and_set/4

    test_and_set(TLog :: tx_tlog:tlog_ext(),
                 Key :: client_key(),
                 OldValue :: client_value(),
                 NewValue :: client_value()) ->
                    {tx_tlog:tlog_ext(), testandset_result()}

### commit/1

    commit(TLog :: tx_tlog:tlog_ext()) -> commit_result()

### read/1

    read(Key :: client_key()) -> read_result()

### write/2

    write(Key :: client_key(), Value :: client_value()) ->
             commit_result()

### add_del_on_list/3

    add_del_on_list(Key :: client_key(),
                    ToAdd :: [client_value()],
                    ToRemove :: [client_value()]) ->
                       listop_result() | {fail, abort, [client_key()]}

### add_on_nr/2

    add_on_nr(Key :: client_key(), ToAdd :: number()) ->
                 numberop_result() | {fail, abort, [client_key()]}

### test_and_set/3

    test_and_set(Key :: client_key(),
                 OldValue :: client_value(),
                 NewValue :: client_value()) ->
                    testandset_result() |
                    {fail, abort, [client_key()]}

### req_list_commit_each/1

    req_list_commit_each(ReqList :: [request_on_key()]) -> [result()]

### get_system_snapshot/0

    get_system_snapshot() ->
                           [tuple()] |
                           {snapshot_failed,
                            intervals:interval(),
                            [tuple()]}

### req_list/2

    req_list(TLog :: tx_tlog:tlog_ext(), ReqList :: [request()]) ->
                {tx_tlog:tlog_ext(), [result()]}

Perform several requests inside a transaction and monitors its execution time.

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