From 780b92ada9afcf1d58085a83a0b9e6bc982203d1 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Tue, 17 Feb 2015 17:25:57 +0000 Subject: Imported from /home/lorry/working-area/delta_berkeleydb/db-6.1.23.tar.gz. --- docs/programmer_reference/apprec_config.html | 260 ++++++++++++++++----------- 1 file changed, 155 insertions(+), 105 deletions(-) (limited to 'docs/programmer_reference/apprec_config.html') diff --git a/docs/programmer_reference/apprec_config.html b/docs/programmer_reference/apprec_config.html index 444c484a..cfac265c 100644 --- a/docs/programmer_reference/apprec_config.html +++ b/docs/programmer_reference/apprec_config.html @@ -14,7 +14,7 @@
-

Library Version 11.2.5.3

+

Library Version 12.1.6.1

@@ -22,9 +22,8 @@ - +
Prev Chapter 14.  - Application Specific Logging and Recovery - Chapter 14.  Application Specific Logging and + Recovery  Next
@@ -38,115 +37,167 @@
-

The application should include a dispatch function that dispatches to -appropriate printing and/or recovery functions based on the log record -type and the operation code. The dispatch function should take the same -arguments as the recovery function, and should call the appropriate -recovery and/or printing functions based on the log record type and the -operation code. For example, the ex_apprec dispatch function is as -follows:

+

+ The application should include a dispatch function that + dispatches to appropriate printing and/or recovery functions + based on the log record type and the operation code. The + dispatch function should take the same arguments as the + recovery function, and should call the appropriate recovery + and/or printing functions based on the log record type and the + operation code. For example, the ex_apprec dispatch function + is as follows: + 

int
 apprec_dispatch(dbenv, dbt, lsn, op)
-	DB_ENV *dbenv;
-	DBT *dbt;
-	DB_LSN *lsn;
-	db_recops op;
+    DB_ENV *dbenv;
+    DBT *dbt;
+    DB_LSN *lsn;
+    db_recops op;
 {
-	u_int32_t rectype;
-	/* Pull the record type out of the log record. */
-	memcpy(&rectype, dbt->data, sizeof(rectype));
-	switch (rectype) {
-	case DB_ex_apprec_mkdir:
-		return (ex_apprec_mkdir_recover(dbenv, dbt, lsn, op));
-	default:
-		/*
-		 * We've hit an unexpected, allegedly user-defined record
-		 * type.
-		 */
-		dbenv->errx(dbenv, "Unexpected log record type encountered");
-		return (EINVAL);
-	}
+    u_int32_t rectype;
+    /* Pull the record type out of the log record. */
+    memcpy(&rectype, dbt->data, sizeof(rectype));
+    switch (rectype) {
+    case DB_ex_apprec_mkdir:
+       return (ex_apprec_mkdir_recover(dbenv, dbt, lsn, op));
+    default:
+        /*
+         * We've hit an unexpected, allegedly user-defined record
+         * type.
+         */
+        dbenv->errx(dbenv, "Unexpected log record type encountered");
+        return (EINVAL);
+    }
 }
-

Applications use this dispatch function and the automatically generated -functions as follows:

+

+ Applications use this dispatch function and the + automatically generated functions as follows: +

    -
  1. When the application starts, call the DB_ENV->set_app_dispatch() -with your dispatch function.
    2. -
  2. Issue a DB_ENV->txn_begin() call before any operations you want to be -transaction-protected.
    3. -
  3. Before accessing any data, issue the appropriate lock call to lock the -data (either for reading or writing).
    4. -
  4. Before modifying any data that is transaction-protected, issue a call -to the appropriate log function.
    5. -
  5. Call DB_TXN->commit() -to cancel all of the modifications.
    6. +
  6. + When the application starts, call the + DB_ENV->set_app_dispatch() with your dispatch + function. +
    7. +
  7. + Issue a DB_ENV->txn_begin() call before any operations you + want to be transaction-protected. +
    8. +
  8. + Before accessing any data, issue the appropriate + lock call to lock the data (either for reading or + writing). +
    9. +
  9. + Before modifying any data that is + transaction-protected, issue a call to the appropriate log + function. +
    10. +
  10. + Call DB_TXN->commit() to cancel all of the + modifications. +
-

The recovery functions are called in the three following cases:

+

+ The recovery functions are called in the three following + cases: +

    -
  1. During recovery after application or system failure, with op set to -DB_TXN_FORWARD_ROLL or DB_TXN_BACKWARD_ROLL.
    2. -
  2. During transaction abort, with op set to DB_TXN_ABORT.
    3. -
  3. On a replicated client to apply updates from the master, with op set to -DB_TXN_APPLY.
    4. +
  4. + During recovery after application or system failure, + with op set to DB_TXN_FORWARD_ROLL or + DB_TXN_BACKWARD_ROLL. +
    5. +
  5. + During transaction abort, with op set to + DB_TXN_ABORT. +
    6. +
  6. + On a replicated client to apply updates from the + master, with op set to DB_TXN_APPLY. +
-

For each log record type you declare, you must write the appropriate -function to undo and redo the modifications. The shell of these -functions will be generated for you automatically, but you must fill in -the details.

-

Your code must be able to detect whether the described modifications -have been applied to the data. The function will be called with the -"op" parameter set to DB_TXN_ABORT when a transaction that wrote -the log record aborts, with DB_TXN_FORWARD_ROLL and -DB_TXN_BACKWARD_ROLL during recovery, and with DB_TXN_APPLY -on a replicated client.

-

The actions for DB_TXN_ABORT and DB_TXN_BACKWARD_ROLL -should generally be the same, and the actions for -DB_TXN_FORWARD_ROLL and DB_TXN_APPLY should generally -be the same. However, if the application is using Berkeley DB replication -and another thread of control may be performing read operations while -log records are applied on a replication client, the recovery function -should perform appropriate locking during DB_TXN_APPLY -operations. In this case, the recovery function may encounter deadlocks -when issuing locking calls. The application should run with the -deadlock detector, and the recovery function should simply return -DB_LOCK_DEADLOCK if a deadlock is detected and a locking -operation fails with that error.

-

The DB_TXN_PRINT operation should print the log record, -typically using the auto-generated print function; it is not used in -the Berkeley DB library, but may be useful for debugging, as in the -db_printlog utility. Applications may safely ignore this -operation code, they may handle printing from the recovery function, or -they may dispatch directly to the auto-generated print function.

-

One common way to determine whether operations need to be undone or -redone is the use of log sequence numbers (LSNs). For example, each -access method database page contains the LSN of the most recent log -record that describes a modification to the page. When the access -method changes a page, it writes a log record describing the change and -including the LSN that was on the page before the change. This LSN is -referred to as the previous LSN. The recovery functions read the page -described by a log record, and compare the LSN on the page to the LSN -they were passed.

-

If the page LSN is less than the passed LSN and the operation is an -undo, no action is necessary (because the modifications have not been -written to the page). If the page LSN is the same as the previous LSN -and the operation is a redo, the actions described are reapplied to the -page. If the page LSN is equal to the passed LSN and the operation is -an undo, the actions are removed from the page; if the page LSN is -greater than the passed LSN and the operation is a redo, no further -action is necessary. If the action is a redo and the LSN on the page -is less than the previous LSN in the log record, it is an error because -it could happen only if some previous log record was not processed.

-

Examples of other recovery functions can be found in the Berkeley DB library -recovery functions (found in files named XXX_rec.c) and in the -application-specific recovery example (specifically, ex_apprec_rec.c).

-

Finally, applications need to ensure that any data modifications they -have made, that were part of a committed transaction, must be written -to stable storage before calling the DB_ENV->txn_checkpoint() method. This is -to allow the periodic removal of database environment log files.

+

+ For each log record type you declare, you must write the + appropriate function to undo and redo the modifications. The + shell of these functions will be generated for you + automatically, but you must fill in the details. +

+

+ Your code must be able to detect whether the described + modifications have been applied to the data. The function will + be called with the "op" parameter set to DB_TXN_ABORT when a + transaction that wrote the log record aborts, with + DB_TXN_FORWARD_ROLL and DB_TXN_BACKWARD_ROLL during + recovery, and with DB_TXN_APPLY on a replicated + client. +

+

+ The actions for DB_TXN_ABORT and DB_TXN_BACKWARD_ROLL + should generally be the same, and the actions for + DB_TXN_FORWARD_ROLL and DB_TXN_APPLY should generally be + the same. However, if the application is using Berkeley DB + replication and another thread of control may be performing + read operations while log records are applied on a replication + client, the recovery function should perform appropriate + locking during DB_TXN_APPLY operations. In this case, the + recovery function may encounter deadlocks when issuing locking + calls. The application should run with the deadlock detector, + and the recovery function should simply return DB_LOCK_DEADLOCK + if a deadlock is detected and a locking operation fails with that error. +

+

+ The DB_TXN_PRINT operation should print the log record, + typically using the auto-generated print function; it is not + used in the Berkeley DB library, but may be useful for + debugging, as in the db_printlog utility. Applications may safely + ignore this operation code, they may handle printing from the + recovery function, or they may dispatch directly to the + auto-generated print function. +

+

+ One common way to determine whether operations need to be + undone or redone is the use of log sequence numbers (LSNs). + For example, each access method database page contains the LSN + of the most recent log record that describes a modification to + the page. When the access method changes a page, it writes a + log record describing the change and including the LSN that + was on the page before the change. This LSN is referred to as + the previous LSN. The recovery functions read the page + described by a log record, and compare the LSN on the page to + the LSN they were passed. +

+

+ If the page LSN is less than the passed LSN and the + operation is an undo, no action is necessary (because the + modifications have not been written to the page). If the page + LSN is the same as the previous LSN and the operation is a + redo, the actions described are reapplied to the page. If the + page LSN is equal to the passed LSN and the operation is an + undo, the actions are removed from the page; if the page LSN + is greater than the passed LSN and the operation is a redo, no + further action is necessary. If the action is a redo and the + LSN on the page is less than the previous LSN in the log + record, it is an error because it could happen only if some + previous log record was not processed. +

+

+ Examples of other recovery functions can be found in the + Berkeley DB library recovery functions (found in files named + XXX_rec.c) and in the application-specific recovery example + (specifically, ex_apprec_rec.c). +

+

+ Finally, applications need to ensure that any data + modifications they have made, that were part of a committed + transaction, must be written to stable storage before calling + the DB_ENV->txn_checkpoint() method. This is to allow the periodic + removal of database environment log files. +

@@ -159,13 +210,12 @@ to allow the periodic removal of database environment log files.

 Next - Automatically generated functions  + Automatically generated + functions  Home -  Chapter 15.  - Programmer Notes - +  Chapter 15.  Programmer Notes
-- cgit v1.2.1