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/rep_mgrmulti.html | 293 ++++++++++++++++++---------- 1 file changed, 193 insertions(+), 100 deletions(-) (limited to 'docs/programmer_reference/rep_mgrmulti.html') diff --git a/docs/programmer_reference/rep_mgrmulti.html b/docs/programmer_reference/rep_mgrmulti.html index 95ce092a..8adf92d1 100644 --- a/docs/programmer_reference/rep_mgrmulti.html +++ b/docs/programmer_reference/rep_mgrmulti.html @@ -8,23 +8,22 @@ - - + +

Library Version 11.2.5.3

Library Version 12.1.6.1

- + - +

Running Replication Manager in multiple processes			Running Replication Manager in + multiple processes
Prev	Chapter 12. - Berkeley DB Replication -	Chapter 12. Berkeley DB Replication	Next

@@ -34,7 +33,8 @@

Running Replication Manager in multiple processes

Running Replication Manager in + multiple processes

@@ -42,164 +42,256 @@

- One replication process and multiple subordinate processes + One replication process and multiple subordinate + processes
- Persistence of local site network address configuration + Persistence of local site network address + configuration
- Programming considerations + Programming considerations
- Handling failure + Handling failure
- Other miscellaneous rules + Other miscellaneous rules

Replication Manager supports shared access to a database environment -from multiple processes.

+ Replication Manager supports shared access to a database + environment from multiple processes or environment handles. +

One replication process and multiple subordinate processes

One replication process and multiple subordinate + processes

Each site in a replication group has just one network address (TCP/IP -host name and port number). This means that only one process can -accept incoming connections. At least one application process must -invoke the DB_ENV->repmgr_start() method to initiate communications -and management of the replication state.

If it is convenient, multiple processes may issue calls to the -Replication Manager configuration methods, and multiple processes may -call DB_ENV->repmgr_start(). Replication Manager automatically opens -the TCP/IP listening socket in the first process to do so (we'll call -it the "replication process" here), and ignores this step in any -subsequent processes ("subordinate processes").

+ Each site in a replication group has just one network + address (TCP/IP host name and port number). This means + that only one process can accept incoming connections. At + least one application process must invoke the + DB_ENV->repmgr_start() method to initiate communications and + management of the replication state. This is called the + replication process. That is, the + replication process is the Replication Manager process + that is responsible for initiating and processing most + replication messages. +

+ If it is convenient, multiple processes may issue calls + to the Replication Manager configuration methods, and + multiple processes may call DB_ENV->repmgr_start(). Replication + Manager automatically opens the TCP/IP listening socket in + the first process to do so, and so this becomes the + replication process. Replication Manager ignores this step + in any subsequent processes, called subordinate + processes. +

+ If the replication process quits and there are one or + more subordinate processes available, one subordinate + process will automatically take over as the replication + process. During an automatic takeover on the master site, + the rest of the replication group briefly delays elections + to prevent an unnecessary change of master. Automatic + takeover does not occur if the replication process fails + unexpectedly. Automatic takeover is most reliable when the + DB_REP_ACK_TIMEOUT is the same value on all sites in the + replication group. +

Persistence of local site network address configuration

Persistence of local site network address + configuration

The local site network address is stored in shared memory, -and remains intact even when (all) processes close their environment -handles gracefully and terminate. A process which opens an -environment handle without running recovery automatically inherits the -existing local site network address configuration. Such a process may not -change the local site address (although it is allowed to redundantly -specify a local site configuration matching that which is already in -effect).

In order to change the local site network address, the application -must run recovery. The application can then specify a new local site -address before restarting Replication Manager. The application should also -remove the old local site address from the replication group if it is no -longer needed.

+ The local site network address is stored in shared + memory, and remains intact even when (all) processes close + their environment handles gracefully and terminate. A + process which opens an environment handle without running + recovery automatically inherits the existing local site + network address configuration. Such a process may not + change the local site address (although it is allowed to + redundantly specify a local site configuration matching + that which is already in effect). +

+ In order to change the local site network address, the + application must run recovery. The application can then + specify a new local site address before restarting + Replication Manager. The application should also remove + the old local site address from the replication group if + it is no longer needed. +

Programming considerations

Note that Replication Manager applications must follow all the usual -rules for Berkeley DB multi-threaded and/or multi-process -applications, such as ensuring that the recovery operation occurs -single-threaded, only once, before any other thread or processes -operate in the environment. -Since Replication Manager creates its own background threads which -operate on the environment, -all environment handles must be opened with the DB_THREAD flag, even -if the application is otherwise single-threaded per process.

At the replication master site, each Replication Manager process opens -outgoing TCP/IP connections to all clients in the replication group. -It uses these direct connections to send to clients any log records -resulting from update transactions that the process executes. But all -other replication activity —message processing, elections, -etc.— takes place only in the "replication process".

Replication Manager notifies the application of certain events, using -the callback function configured with the DB_ENV->set_event_notify() -method. These notifications occur only in the process where the event -itself occurred. Generally this means that most notifications occur -only in the "replication process". Currently the only replication -notification that can occur in a "subordinate process" is -DB_EVENT_REP_PERM_FAILED.

It is not supported for a process running Replication Manager to -spawn a subprocess.

+ Note that Replication Manager applications must follow + all the usual rules for Berkeley DB multi-threaded and/or + multi-process applications, such as ensuring that the + recovery operation occurs single-threaded, only once, + before any other thread or processes operate in the + environment. Since Replication Manager creates its own + background threads which operate on the environment, all + environment handles must be opened with the DB_THREAD + flag, even if the application is otherwise single-threaded + per process. +

+ At the replication master site, each Replication + Manager process opens outgoing TCP/IP connections to all + clients in the replication group. It uses these direct + connections to send to clients any log records resulting + from update transactions that the process executes. But + all other replication activity —message processing, + elections, etc.— takes place only in the + "replication process". +

+ Replication Manager notifies the application of certain + events, using the callback function configured with the + DB_ENV->set_event_notify() method. These notifications occur only + in the process where the event itself occurred. Generally + this means that most notifications occur only in the + replication process. Currently there are only two + replication notification that can occur in a subordinate + process: +

+
+ DB_EVENT_REP_PERM_FAILED. +
+
+
+ DB_EVENT_REP_AUTOTAKEOVER_FAILED +
+

+ It is not supported for a process running Replication + Manager to spawn a subprocess. In an application where + a parent process spawns child subprocesses, Replication + Manager can only run in the spawned child subprocesses. + The following operations do not run Replication Manager + and can safely be performed in the parent process: opening + or closing an environment handle, running DB_ENV->failchk(), + running recovery. The following operations can implicitly + run a Replication Manager thread and should only be performed + in a child subprocess: opening or closing a database handle, + transactions, gets, puts, checkpoints. +

+ If your application is a group of related processes managed + by a single "watcher" process (as described in + Architecting Transactional Data + Store applications), + the "watcher" process is the parent process and is subject to + the same restrictions. +

Handling failure

Multi-process Replication Manager applications should handle failures -in a manner consistent with the rules described in -Handling failure in Transactional Data Store applications. -To summarize, there are -two ways to handle failure of a process:

+ Multi-process Replication Manager applications should + handle failures in a manner consistent with the rules + described in Handling failure in Transactional Data Store applications. To summarize, there + are two ways to handle failure of a process: +

- The simple way is to kill all remaining processes, run - recovery, and then restart all processes from the beginning. - But this can be a bit drastic. -
+ The simple way is to kill all remaining + processes, run recovery, and then restart all + processes from the beginning. But this can be a + bit drastic. +
- Using the DB_ENV->failchk() method, it is sometimes possible to - leave surviving processes running, and just restart the failed - process. -
-
- Multi-process Replication Manager applications using this - technique must start a new process when an old process fails. - It is not possible for a "subordinate process" to take over the - duties of a failed "replication process". If the failed - process happens to be the replication process, then after a - failchk() call the next process to call DB_ENV->repmgr_start() will - become the new replication process. -
+ Using the DB_ENV->failchk() method, it is sometimes + possible to leave surviving processes running, and + just restart the failed process. +
+
+ Multi-process Replication Manager applications + using this technique must start a new process when + an old process fails. A subordinate process cannot + automatically take over as the replication process + if the previous replication process failed. If the + failed process happens to be the replication + process, then after a + failchk() call, the + next process to call DB_ENV->repmgr_start() will become the + new replication process. +

Other miscellaneous rules

A database environment may not be shared between a Replication -Manager application process and a Base API application process.
It is not possible to run multiple Replication Manager processes -during mixed-version live upgrades from Berkeley DB versions prior -to 4.8.
+
+ A database environment may not be shared + between a Replication Manager application process + and a Base API application process. +
+
+
+ It is not possible to run multiple Replication + Manager processes during mixed-version live + upgrades from Berkeley DB versions prior to 4.8. +
+

@@ -215,11 +307,12 @@ to 4.8. Next - Managing Replication Files + Managing replication directories and files Home - Running Replication using the db_replicate Utility + Running replication using the + db_replicate utility -- cgit v1.2.1