NAME
    Perinci::Tx::Manager - A Rinci transaction manager

VERSION
    This document describes version 0.57 of Perinci::Tx::Manager (from Perl
    distribution Perinci-Tx-Manager), released on 2017-07-10.

SYNOPSIS
     # used by Perinci::Access::Schemeless

DESCRIPTION
    This class implements transaction and undo manager (TM), as specified by
    Rinci::function::Transaction and Riap::Transaction. It is meant to be
    instantiated by Perinci::Access::Schemeless, but will also be passed to
    transactional functions to save undo/redo data.

    It uses SQLite database to store transaction list and undo/redo data as
    well as transaction data directory to provide trash_dir/tmp_dir for
    functions that require it.

ATTRIBUTES
  _tx_id
    This is just a convenience so that methods that require tx_id will get
    the default value from here if tx_id not specified in arguments.

METHODS
  new(%args) => OBJ
    Create new object. Arguments:

    *   pa => OBJ

        Perinci::Access::Schemeless object. This is required by
        Perinci::Tx::Manager to load/get functions when it wants to perform
        undo/redo/recovery. Perinci::Access::Schemeless conveniently
        require() the Perl modules and wraps the functions.

    *   data_dir => STR (default "~/.perinci/.tx")

    *   max_txs => INT (default 1000)

        Limit maximum number of transactions maintained by the TM, including
        all rolled back and committed transactions, since they are still
        recorded in the database. The default is 1000.

        Not yet implemented.

        After this limit is reached, cleanup will be performed to delete
        rolled back transactions, and after that committed transactions.

    *   max_open_txs => INT (default 100)

        Limit maximum number of open (in progress, aborted, prepared)
        transactions. This exclude resolved transactions (rolled back and
        committed). The default is no limit.

        Not yet implemented.

        After this limit is reached, starting a new transaction will fail.

    *   max_committed_txs => INT (default 100)

        Limit maximum number of committed transactions that is recorded by
        the database. This is equal to the number of undo steps that are
        remembered.

        After this limit is reached, cleanup will automatically be performed
        so that the oldest committed transactions are purged.

        Not yet implemented.

    *   max_open_age => INT

        Limit the maximum age of open transactions (in seconds). If this
        limit is reached, in progress transactions will automatically be
        purged because it times out.

        Not yet implemented.

    *   max_committed_age => INT

        Limit the maximum age of committed transactions (in seconds). If
        this limit is reached, the old transactions will start to be purged.

        Not yet implemented.

  $tx->get_trash_dir => RESP
  $tx->get_tmp_dir => RESP
  $tm->begin(%args) => RESP
    Start a new transaction.

    Arguments: tx_id (str, required, unless already supplied via _tx_id()),
    twopc (bool, optional, currently must be false since distributed
    transaction is not yet supported), summary (optional).

    TM will create an entry for this transaction in its database.

  $tm->action(%args) => RESP
    Perform action for the transaction by calling one or more functions.

    Arguments: "f" (fully-qualified function name), "args" (arguments to
    function, hashref). Or, "actions" (list of function calls, array, "[[f1,
    args1], ...]", alternative to specifying "f" and "args"), "confirm"
    (bool, if set to true then will pass "-confirm => 1" special argument to
    functions; see status code 331 in Rinci::function for more details on
    this).

    TM will also pass the following special arguments: "-tx_v =>
    PROTO_VERSION", "-tx_rollback => 1" during rollback, and "-tx_recovery
    => 1" during recovery, for informative purposes.

    To perform a single action, specify "f" and "args". To perform several
    actions, supply "actions".

    Note: special arguments (those started with dash, "-") will be stripped
    from function arguments by TM.

    If response from function is not success, rollback() will be called.

    Tip: To call in dry-run mode to function supporting dry-run mode, or to
    call a pure function, you do not have to use TM's action() but rather
    call the function directly, since this will not have any side effects.

    Tip: During "fix_state", function can return "stash" in result metadata
    which can be set to hash. This will be collected and passed by TM in
    "-stash" special argument. This is useful in multiple actions where one
    action might need to check result from previous action.

  $tx->commit(%args) => RESP
    Commit a transaction.

    Arguments: "tx_id"

  $tx->rollback(%args) => RESP
    Rollback a transaction.

    Arguments: "tx_id", "sp_id" (optional, savepoint name to rollback to a
    specific savepoint only).

    Currently rolling back to a savepoint is not implemented.

  $tx->prepare(%args) => RESP
    Prepare a transaction.

    Arguments: "tx_id"

    Currently will return 501 (not implemented). Rinci::Transaction does not
    yet support distributed transaction.

  $tx->savepoint(%args) => RESP
    Declare a savepoint.

    Arguments: "tx_id", "sp_id" (savepoint name).

    Currently not implemented.

  $tx->release_savepoint(%args) => RESP
    Release (forget) a savepoint.

    Arguments: "tx_id", "sp_id" (savepoint name).

    Currently not implemented.

  $tx->undo(%args) => RESP
    Undo a committed transaction.

    Arguments: "tx_id", "confirm" (bool, if set to true then will pass
    "-confirm => 1" special argument to functions; see status code 331 in
    Rinci::function for more details on this).

  $tx->redo(%args) => RESP
    Redo an undone committed transaction.

    Arguments: "tx_id", "confirm" (bool, if set to true then will pass
    "-confirm => 1" special argument to functions; see status code 331 in
    Rinci::function for more details on this).

  $tx->list(%args) => RESP
    List transactions.

    Arguments: detail (bool, default 0, whether to return transaction
    records instead of just a list of transaction ID's).

    Return an array of results sorted by creation date (in ascending order).

  $tx->discard(%args) => RESP
    Discard (forget) a client's committed transaction.

    Arguments: "tx_id"

    Transactions that can be discarded are committed, undone committed, or
    inconsistent ones (i.e., those with final statuses "C", "U", "X").

  $tm->discard_all(%args) => RESP
    Discard (forget) all committed transactions.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Perinci-Tx-Manager>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Perinci-Tx-Manager>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-Tx-Manager>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    Rinci::Transaction

    Perinci::Access::Schemeless

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2017, 2016, 2015, 2014, 2013, 2012 by
    perlancar@cpan.org.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

