Олег Давидович: 1 версия импортирована

2024-10-21T08:51:08Z

1 версия импортирована

← Предыдущая версия	Версия от 08:51, 21 октября 2024
(нет различий)

1>Skodak: /* The Flow */

2009-11-08T20:20:08Z

The Flow

Новая страница

{{Work in progress}}{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}__NOTOC__
=== General principles ===

# Everybody thinks it's a good idea to have those logical nested transactions in Moodle (but me and ML)
# No matter of they nested nature, they are really '''"delegated transactions"''' (so outer levels get the control over inner ones), so we are going to apply that naming to enforce the real concept.
# Code will '''never''' rely on rollback happening. it's only a maeasure to reduce (not to eliminate) DB garbled information.
# Any problem related with the use of transactions (unfinished ones, unbalanced, finished twice...) will end '''always''' with one transaction_exception that will '''always''' end performing one DB rollback.
# If one transaction (at any level) has been marked for rollback() there won't be any method to change it. Finally Moodle will perform the DB rollback.
# If one transaction (at any level) has been marked for commit() it will be possible to change that status to rollback() in any outer level.
# It will be '''optional''' to catch exceptions when using transactions, but if they are caught, then it's mandatory to mark the transaction for rollback()
# Any explicit rollback() call will pass the exception originating it, i.e. rollback($exception) to be re-thrown.
# API will work in a natural and similar fashion to current recordsets one.
# We'll start '''recommending''' to use InnoDB for 2.0 in environmental tests. Posibly, at some point in the future that will become a '''must'''. But '''it is not''' for now (be warned!).

=== The API ===

# All the handling must go, exclusively, to moodle_database object, leaving real drivers only implementing (protected) the old begin/commit/rollback_sql() functions.
# One array of objects of type moodle_delegated_transaction will be stored / checked from $DB
# $DB will be the responsible to instantiate / accumulate / pair / compare moodle_delegated_transactions
# Each moodle_transaction will be able to set the global mark for rollback. Commit won't change anything.
# Inner-most commit/rollback will printout one complete stack of moodle_transactions information if we are under DEBUG_DEVELOPER and new setting (delegatedtransactionsdebug) is enabled.
# Normal usage of the moodle_transaction will be:
<code php>
$transaction = $DB->start_delegated_transaction();
// Perform some $DB stuff
$transaction->allow_commit();
</code>
7. If, for any reason, developer needs to catch exceptions when using transactions, it will be mandatory to use it in this way:
<code php>
try {
$transaction = $DB->start_delegated_transaction();
// Perform some $DB stuff
$transaction->allow_commit();
} catch (Exception $e) {
//extra cleanup steps
$transaction->rollback($e); // rethrows exception
}
</code>
8. In order to be able to keep some parts of code out from top transactions completely, if we know it can lead to problems, we can use:
<code php>
$DB->transactions_forbidden(); // Instant check to confirm we aren't using transactions in this point. Will throw exception if transaction is found.
</code>

===The Flow===

[[Image:TransactionsAndExceptionsFlow.png|thumb|right|caption]]
# Any default exception handler will:
## Catch uncaught transaction_exception exceptions,
## Properly perform the DB rollback
## debug/error/log honouring related settings.
## inform with as many details as possible (token, place... whatever).
# Any "footer" (meaning some place before ending <html> output) will:
## Detect "in-transaction" status.
## Let execution continue, transaction is automatically rolled back in $DB->dispose()
## inform with as many details as possible (token, place... whatever).
# $DB->dispose() will:
## Detect "in-transaction" status.
## log error (not possible to honour settings!)
## Properly perform the full DB rollback

===Related tasks===

# Move this to MoodleDocs and publicy in Dev Forum.
# Implement fulfilling current specs / review / test iterations
# Re-enforce in Docs, phpdocs, everywhere, the "Code will *never* rely on rollback happening" and the "delegated" nature of the whole thing.
# Be extremely careful about any use of delegated transactions until we get used to them, reviewing them in core often.
# Point somewhere about the move to InnoDB, pros/cons, migration process... to have it documented.

Development:DB layer 2.0 delegated transactions - История изменений

Олег Давидович: 1 версия импортирована

1>Skodak: /* The Flow */