.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "PMEMKV_TX" "3" "2021-07-26" "PMEMKV - pmemkv version 1.5.0-rc1" "PMEMKV Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2019-2021, Intel Corporation
.SH NAME
.PP
\f[B]pmemkv_tx\f[R] - Transactions API for libpmemkv
.PP
This API is \f[B]EXPERIMENTAL\f[R] and might change.
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmemkv.h>

int pmemkv_tx_begin(pmemkv_db *db, pmemkv_tx **tx);
int pmemkv_tx_put(pmemkv_tx *tx, const char *k, size_t kb, const char *v, size_t vb);
int pmemkv_tx_remove(pmemkv_tx *tx, const char *k, size_t kb);
int pmemkv_tx_commit(pmemkv_tx *tx);
void pmemkv_tx_abort(pmemkv_tx *tx);
void pmemkv_tx_end(pmemkv_tx *tx);
\f[R]
.fi
.SH DESCRIPTION
.PP
The transaction allows grouping \f[C]put\f[R] and \f[C]remove\f[R]
operations into a single atomic action (with respect to persistence and
concurrency).
Concurrent engines provide transactions with ACID (atomicity,
consistency, isolation, durability) properties.
Transactions for single threaded engines provide atomicity, consistency
and durability.
Actions in a transaction are executed in the order in which they were
called.
.TP
\f[B]\f[CB]int pmemkv_tx_begin(pmemkv_db *db, pmemkv_tx **tx);\f[B]\f[R]
Starts a pmemkv transaction and stores a pointer to a
\f[I]pmemkv_tx\f[R] instance in \f[C]*tx\f[R].
.TP
\f[B]\f[CB]int pmemkv_tx_put(pmemkv_tx *tx, const char *k, size_t kb, const char *v, size_t vb);\f[B]\f[R]
Inserts a key-value pair into pmemkv database.
\f[C]kb\f[R] is the length of the key \f[C]k\f[R] and \f[C]vb\f[R] is
the length of value \f[C]v\f[R].
When this function returns, caller is free to reuse both buffers.
The inserted element is visible only after calling pmemkv_tx_commit.
.TP
\f[B]\f[CB]int pmemkv_tx_remove(pmemkv_tx *tx, const char *k, size_t kb);\f[B]\f[R]
Removes record with the key \f[C]k\f[R] of length \f[C]kb\f[R].
The removed elements are still visible until calling pmemkv_tx_commit.
This function will succeed even if there is no element in the database.
.TP
\f[B]\f[CB]int pmemkv_tx_commit(pmemkv_tx *tx);\f[B]\f[R]
Commits the transaction.
All operations of this transaction are applied as a single power
fail-safe atomic action.
.TP
\f[B]\f[CB]void pmemkv_tx_abort(pmemkv_tx *tx);\f[B]\f[R]
Discards all uncommitted operations.
.TP
\f[B]\f[CB]void pmemkv_tx_end(pmemkv_tx *tx);\f[B]\f[R]
Deletes the pmemkv transaction object and discards all uncommitted
operations.
.SS ERRORS
.PP
Each function, except for \f[I]pmemkv_tx_abort()\f[R] and
\f[I]pmemkv_tx_end()\f[R] returns status.
Possible return values are listed in \f[B]libpmemkv\f[R](3).
.SH EXAMPLE
.PP
The following example is taken from
\f[C]examples/pmemkv_transaction_c\f[R] directory.
.PP
Usage of pmemkv transaction in C:
.IP
.nf
\f[C]
#include <assert.h>
#include <libpmemkv.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define ASSERT(expr)                                                                     \[rs]
    do {                                                                             \[rs]
        if (!(expr))                                                             \[rs]
            puts(pmemkv_errormsg());                                         \[rs]
        assert(expr);                                                            \[rs]
    } while (0)

#define LOG(msg) puts(msg)

/*
 * This example expects a path to already created database pool.
 *
 * To create a pool use one of the following commands.
 *
 * For regular pools use:
 * pmempool create -l -s 1G \[dq]pmemkv_radix\[dq] obj path_to_a_pool
 *
 * For poolsets use:
 * pmempool create -l \[dq]pmemkv_radix\[dq] obj ../examples/example.poolset
 */
int main(int argc, char *argv[])
{
    if (argc < 2) {
        printf(\[dq]Usage: %s pool\[rs]n\[dq], argv[0]);
        exit(1);
    }

    /* See libpmemkv_config(3) for more detailed example of config creation */
    LOG(\[dq]Creating config\[dq]);
    pmemkv_config *cfg = pmemkv_config_new();
    ASSERT(cfg != NULL);

    int s = pmemkv_config_put_path(cfg, argv[1]);
    ASSERT(s == PMEMKV_STATUS_OK);

    LOG(\[dq]Opening pmemkv database with \[aq]radix\[aq] engine\[dq]);
    pmemkv_db *db = NULL;
    s = pmemkv_open(\[dq]radix\[dq], cfg, &db);
    ASSERT(s == PMEMKV_STATUS_OK);
    ASSERT(db != NULL);

    const char *key1 = \[dq]key1\[dq];
    const char *value1 = \[dq]value1\[dq];
    const char *key2 = \[dq]key2\[dq];
    const char *value2 = \[dq]value2\[dq];
    const char *key3 = \[dq]key3\[dq];
    const char *value3 = \[dq]value3\[dq];

    LOG(\[dq]Putting new key\[dq]);
    s = pmemkv_put(db, key1, strlen(key1), value1, strlen(value1));
    ASSERT(s == PMEMKV_STATUS_OK);

    LOG(\[dq]Starting a tx\[dq]);
    pmemkv_tx *tx;
    s = pmemkv_tx_begin(db, &tx);
    ASSERT(s == PMEMKV_STATUS_OK);

    s = pmemkv_tx_remove(tx, key1, strlen(key1));
    s = pmemkv_tx_put(tx, key2, strlen(key2), value2, strlen(value2));
    s = pmemkv_tx_put(tx, key3, strlen(key3), value3, strlen(value3));

    /* Until transaction is committed, changes are not visible */
    s = pmemkv_exists(db, key1, strlen(key1));
    ASSERT(s == PMEMKV_STATUS_OK);
    s = pmemkv_exists(db, key2, strlen(key2));
    ASSERT(s == PMEMKV_STATUS_NOT_FOUND);
    s = pmemkv_exists(db, key3, strlen(key3));
    ASSERT(s == PMEMKV_STATUS_NOT_FOUND);

    s = pmemkv_tx_commit(tx);
    ASSERT(s == PMEMKV_STATUS_OK);

    /* Changes are now visible and pmemkv_tx object is destroyed */
    s = pmemkv_exists(db, key1, strlen(key1));
    ASSERT(s == PMEMKV_STATUS_NOT_FOUND);
    s = pmemkv_exists(db, key2, strlen(key2));
    ASSERT(s == PMEMKV_STATUS_OK);
    s = pmemkv_exists(db, key3, strlen(key3));
    ASSERT(s == PMEMKV_STATUS_OK);

    LOG(\[dq]Ending transaction\[dq]);
    pmemkv_tx_end(tx);

    LOG(\[dq]Closing database\[dq]);
    pmemkv_close(db);

    return 0;
}
\f[R]
.fi
.SH SEE ALSO
.PP
\f[B]libpmemkv\f[R](7), \f[B]libpmemkv\f[R](3) and
\f[B]<https://pmem.io>\f[R]