The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Perinci-Tx-Manager-0.47
River stage two • 14 direct dependents • 19 total dependents
++
/ Perinci::Tx::Manager

NAME

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

VERSION

version 0.47

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

HOMEPAGE

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

SOURCE

Source repository is at https://github.com/sharyanto/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.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Steven Haryanto.

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