1<!--$Id: comm.so,v 1.19 2007/03/20 20:20:27 alanb Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Building the communications infrastructure</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></b></td> 13<td align=right><a href="../rep/base_meth.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/newsite.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Building the communications infrastructure</b></p> 16<p>Replication Manager provides a built-in communications 17infrastructure.</p> 18<p>For applications that use the Base replication API, which must provide 19their own communications infrastructure, it is typically written with one 20or more threads of control looping on one or more communication 21channels, receiving and sending messages. These threads accept messages 22from remote environments for the local database environment, and accept 23messages from the local environment for remote environments. Messages 24from remote environments are passed to the local database environment 25using the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method. Messages from the local environment are 26passed to the application for transmission using the callback function 27specified to the <a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method.</p> 28<p>Processes establish communication channels by calling the 29<a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method, regardless of whether they are running in 30client or server environments. This method specifies the <b>send</b> 31function, a callback function used by Berkeley DB for sending messages to 32other database environments in the replication group. The <b>send</b> 33function takes an environment ID and two opaque data objects. It is the 34responsibility of the <b>send</b> function to transmit the information 35in the two data objects to the database environment corresponding to the 36ID, with the receiving application then calling the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method 37to process the message.</p> 38<p>The details of the transport mechanism are left entirely to the 39application; the only requirement is that the data buffer and size of 40each of the control and rec <a href="../../api_c/dbt_class.html">DBT</a>s passed to the <b>send</b> 41function on the sending site be faithfully copied and delivered to the 42receiving site by means of a call to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> with 43corresponding arguments. Messages that are broadcast (whether by 44broadcast media or when directed by setting the 45<a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method's envid parameter DB_EID_BROADCAST), should 46not be processed by the message sender. In all cases, the application's 47transport media or software must ensure that <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> is 48never called with a message intended for a different database 49environment or a broadcast message sent from the same environment on 50which <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> will be called. The <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method is 51free-threaded; it is safe to deliver any number of messages 52simultaneously, and from any arbitrary thread or process in the Berkeley DB 53environment.</p> 54<p>There are a number of informational returns from the 55<a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method:</p> 56<br> 57<b><a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a>, it means that 58another database environment in the replication group also believes 59itself to be the master. The application should complete all active 60transactions, close all open database handles, reconfigure itself as 61a client using the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method, and then call for an election by 62calling the <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method.</ul> 63<b><a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a>, it means 64that another database environment in the replication group has called 65for an election. The application should call the <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method.</ul> 66<b><a href="../../api_c/rep_message.html#DB_REP_IGNORE">DB_REP_IGNORE</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_IGNORE">DB_REP_IGNORE</a>, it means that 67this message cannot be processed. 68This is normally an indication that this message 69is irrelevant to the current replication state, such as a message 70from an old generation that arrived late.</ul> 71<b><a href="../../api_c/rep_message.html#DB_REP_ISPERM">DB_REP_ISPERM</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_ISPERM">DB_REP_ISPERM</a>, it means a 72permanent record, perhaps a message previously returned as 73<a href="../../api_c/rep_message.html#DB_REP_NOTPERM">DB_REP_NOTPERM</a> was successfully 74written to disk. This record may have filled a gap in the log record that 75allowed additional records to be written. The <b>ret_lsnp</b> 76contains the maximum LSN of the permanent records written.</ul> 77<b><a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a>, it means that 78a message from a previously unknown member of the replication group has 79been received. The application should reconfigure itself as necessary 80so it is able to send messages to this site.</ul> 81<b><a href="../../api_c/rep_message.html#DB_REP_NOTPERM">DB_REP_NOTPERM</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_NOTPERM">DB_REP_NOTPERM</a>, it means a 82message marked as <a href="../../api_c/rep_transport.html#DB_REP_PERMANENT">DB_REP_PERMANENT</a> was processed successfully 83but was not written to disk. This is normally an indication that one 84or more messages, which should have arrived before this message, have 85not yet arrived. This operation will be written to disk when the 86missing messages arrive. The <b>ret_lsnp</b> argument will contain 87the LSN of this record. The application should take whatever action 88is deemed necessary to retain its recoverability characteristics.</ul> 89<br> 90<table width="100%"><tr><td><br></td><td align=right><a href="../rep/base_meth.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/newsite.html"><img src="../../images/next.gif" alt="Next"></a> 91</td></tr></table> 92<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 93</body> 94</html> 95
