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.

SEE ALSO

    Rinci::Transaction

    Perinci::Access::Schemeless

