← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/rep/ex_comm.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/ref/rep/ex_comm.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB Reference Guide: Ex_repquote: a TCP/IP based communication infrastructure</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<table width="100%"><tr valign=top>
13
 
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td>
14
 
<td align=right><a href="../../ref/rep/ex.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex_rq.html"><img src="../../images/next.gif" alt="Next"></a>
15
 
</td></tr></table>
16
 
<p>
17
 
<h1 align=center>Ex_repquote: a TCP/IP based communication infrastructure</h1>
18
 
<p>All Berkeley DB replication applications must implement a communication
19
 
infrastructure.  The communication infrastructure consists of three
20
 
parts: a way to map environment IDs to particular sites, the functions
21
 
to get and receive messages, and the application architecture that
22
 
supports the particular communication infrastructure used (for example,
23
 
individual threads per communicating site, a shared message handler for
24
 
all sites, a hybrid solution).  The communication infrastructure is
25
 
implemented in the file <b>ex_repquote/ex_rq_net.c</b>, and each part
26
 
of that infrastructure is described as follows.
27
 
<p>Ex_repquote maintains a table of environment ID to TCP/IP port mappings.
28
 
This table is stored in the app_private field of the <a href="../../api_c/env_class.html">DB_ENV</a>
29
 
object so it can be accessed by any function that has the database
30
 
environment handle.  The table is represented by a machtab_t structure
31
 
which contains a reference to a linked list of member_t's, both of which
32
 
are defined in <b>ex_repquote/ex_rq_net.c</b>.  Each member_t contains
33
 
the host and port identification, the environment ID, and a file
34
 
descriptor.  The table is maintained by the following interfaces:
35
 
<p><blockquote><pre>int machtab_add(machtab_t *machtab, int fd, u_int32_t hostaddr, int port, int *eidp);
36
 
int machtab_init(machtab_t **machtabp, int priority, int nsites);
37
 
int machtab_getinfo(machtab_t *machtab, int eid, u_int32_t *hostp, int *portp);
38
 
void machtab_parm(machtab_t *machtab, int *nump, int *priorityp, u_int32_t *timeoutp);
39
 
int machtab_rem(machtab_t *machtab, int eid, int lock);
40
 
</pre></blockquote>
41
 
<p>These interfaces are particular to this application and communication
42
 
infrastructure, but provide an indication of the sort of functionality
43
 
that is needed to maintain the application-specific state for a
44
 
TCP/IP-based infrastructure.  The goal of the table and its interfaces
45
 
is threefold: First, it must guarantee that given an environment ID,
46
 
the send function can send a message to the appropriate place.  Second,
47
 
when given the special environment ID <a href="../../api_c/rep_transport.html#DB_EID_BROADCAST">DB_EID_BROADCAST</a>, the send
48
 
function can send messages to all the machines in the group.  Third,
49
 
upon receipt of an incoming message, the receive function can correctly
50
 
identify the sender and pass the appropriate environment ID to the
51
 
<a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> method.
52
 
<p>Mapping a particular environment ID to a specific port is accomplished
53
 
by looping through the linked list until the desired environment ID is
54
 
found.  Broadcast communication is implemented by looping through the
55
 
linked list and sending to each member found.  Since each port
56
 
communicates with only a single other environment, receipt of a message
57
 
on a particular port precisely identifies the sender.
58
 
<p>The example provided is merely one way to satisfy these requirements,
59
 
and there are alternative implementations as well.  For instance,
60
 
instead of associating separate socket connections with each remote
61
 
environment, an application might instead label each message with a
62
 
sender identifier; instead of looping through a table and sending a
63
 
copy of a message to each member of the replication group, the
64
 
application could send a single message using a broadcast protocol.
65
 
<p>In ex_repquote's case, the send function (slightly simplified) is as
66
 
follows:
67
 
<pre><p><blockquote>int
68
 
quote_send(dbenv, control, rec, eid, flags)
69
 
        DB_ENV *dbenv;
70
 
        const DBT *control, *rec;
71
 
        int eid;
72
 
        u_int32_t flags;
73
 
{
74
 
        int fd, n, ret;
75
 
        machtab_t *machtab;
76
 
        member_t *m;
77
 
<p>
78
 
        machtab = (machtab_t *)dbenv-&gt;app_private;
79
 
<p>
80
 
        /*
81
 
         * If this is a broadcast, call a separate function to
82
 
         * iterate through the table of environment (a/k/a
83
 
         * machine) IDs and call quote_send_one on each.
84
 
         * (This function is not reproduced here, but can be
85
 
         * seen in ex_rq_net.c.)
86
 
         */
87
 
        if (eid == DB_EID_BROADCAST) {
88
 
                n = quote_send_broadcast(machtab, rec, control, flags);
89
 
                if (n &lt; 0)
90
 
                        return (DB_REP_UNAVAIL);
91
 
                return (0);
92
 
        }
93
 
<p>
94
 
        /* Find the fild descriptor, fd, associated with this EID. */
95
 
        fd = 0;
96
 
        if ((ret = pthread_mutex_lock(&machtab-&gt;mtmutex)) != 0)
97
 
                return (0);
98
 
        for (m = LIST_FIRST(&machtab-&gt;machlist); m != NULL;
99
 
            m = LIST_NEXT(m, links)) {
100
 
                if (m-&gt;eid == eid) {
101
 
                        fd = m-&gt;fd;
102
 
                        break;
103
 
                }
104
 
        }
105
 
        if (pthread_mutex_unlock(&machtab-&gt;mtmutex) != 0)
106
 
                return (-1);
107
 
<p>
108
 
        if (fd == 0)
109
 
                return (DB_REP_UNAVAIL);
110
 
<p>
111
 
        /* We have a file descriptor;  write the data over it. */
112
 
        ret = quote_send_one(rec, control, fd, flags);
113
 
<p>
114
 
        return (ret);
115
 
}
116
 
<p>
117
 
int
118
 
quote_send_broadcast(machtab, rec, control, flags)
119
 
        machtab_t *machtab;
120
 
        const DBT *rec, *control;
121
 
        u_int32_t flags;
122
 
{
123
 
        int ret, sent;
124
 
        member_t *m, *next;
125
 
        if ((ret = pthread_mutex_lock(&machtab-&gt;mtmutex)) != 0)
126
 
                return (0);
127
 
        sent = 0;
128
 
        for (m = LIST_FIRST(&machtab-&gt;machlist); m != NULL; m = next) {
129
 
                next = LIST_NEXT(m, links);
130
 
                if ((ret = quote_send_one(rec, control, m-&gt;fd, flags)) != 0) {
131
 
                        (void)machtab_rem(machtab, m-&gt;eid, 0);
132
 
                } else
133
 
                        sent++;
134
 
        }
135
 
        if (pthread_mutex_unlock(&machtab-&gt;mtmutex) != 0)
136
 
                return (-1);
137
 
        return (sent);
138
 
}</blockquote></pre>
139
 
<p>The quote_send_one function has been omitted as it simply writes the
140
 
data requested over the file descriptor that it is passed.  It contains
141
 
nothing specific to Berkeley DB or this communication infrastructure.  The
142
 
complete code can be found in <b>ex_repquote/ex_rq_net.c</b>.
143
 
<p>The quote_send function is passed as the callback to <a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a>;
144
 
Berkeley DB automatically sends messages as needed for replication.  The
145
 
receive function is a mirror to the quote_send_one function.  It is not
146
 
a callback function (the application is responsible for collecting
147
 
messages and calling <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> on them as is convenient).  In
148
 
the sample application, all messages transmitted are Berkeley DB messages that
149
 
get handled by <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a>, however, this is not always going
150
 
to be the case.  The application may want to pass its own messages
151
 
across the same channels, distinguish between its own messages and those
152
 
of Berkeley DB, and then pass only the Berkeley DB ones to <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a>.
153
 
<p>The final component of the communication infrastructure is the process
154
 
model used to communicate with all the sites in the replication group.
155
 
Each site creates a thread of control that listens on its designated
156
 
socket (as specified by the <b>-m</b> command line argument) and
157
 
then creates a new channel for each site that contacts it.  In addition,
158
 
each site explicitly connects to the sites specified in the
159
 
<b>-o</b> command line argument.  This is a fairly standard TCP/IP
160
 
process architecture and is implemented by the following functions (all
161
 
in <b>ex_repquote/ex_rq_net.c</b>).
162
 
<p><blockquote><pre>int get_connected_socket(machtab_t *machtab, char *progname, char *remotehost,
163
 
int port, int *is_open, int *eidp): Connect to the specified host/port, add the
164
 
site to the machtab, and return a file descriptor for communication with this
165
 
site.
166
 
<p>
167
 
int listen_socket_init(char *progname, int port): Initialize a socket for
168
 
listening on a particular part.
169
 
<p>
170
 
int listen_socket_accept(machtab_t *machtab, char *progname, int socket,
171
 
int *eidp): Accept a connection on a socket and add it to the machtab.
172
 
int listen_socket_connect</pre></blockquote>
173
 
<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/ex.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex_rq.html"><img src="../../images/next.gif" alt="Next"></a>
174
 
</td></tr></table>
175
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
176
 
</body>
177
 
</html>