<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="revision" content="$Id: mailbox-format.html,v 1.9 2010/01/06 17:01:29 murch Exp $" />
<meta name="author" content="Bron Gondwana" />
<title>Index API</title>
</head>
<body>
<h1>Index API</h1>
<h2>Intro</h2>
<p>The Index API is implemented in <tt>imap/index.h</tt> and
<tt>imap/index.c</tt>. It provides a snapshot view into the
underlying mailbox (see <a href="mailbox-api.html">the
Mailbox API documentation</a> which obeys IMAP semantics,
as well as all the searching and sorting logic.
<h2>Opening and closing</h2>
<pre>
struct index_state *state = NULL;
struct index_init init;
int r;
const char *mboxname = "user.brong";
memset(&init, 0, sizeof(struct index_init));
init.userid = imapd_userid;
init.authstate = imapd_authstate;
init.out = imapd_out;
r = index_open(mboxname, &init, &state);
if (r) return r;
do_stuff(state);
index_close(&state);
</pre>
<p>The <tt>index_init</tt> interface sucks. So does passing lots
of parameters. For now, this will do! Just pass NULL if you're
only reading, or use the code already in imapd and you'll be fine.</p>
<h2>The Index Model</h2>
<p>Ok - I think a few words about the index model and how it differs
from direct mailbox access are needed! In the past, index.c used
pointers directly into the mmaped <tt>cyrus.index</tt> file and
maintained the old mmaped copy if an expunge took place. Under the
namelock regime, this is no longer required because namelocks will
avoid the file being re-written.</p>
<p>Also, memory is now cheap. Rather than using locks to ensure
consistency, we just keep a copy of the <tt>struct index_record</tt>
for even message in the index, stored in memory. Since these are
about 100 bytes each, a 1 million email mailbox will take rougly
100Mb of memory. That's not too bad on a modern server, and that's
a <b>huge</b> mailbox.</p>
<p>So - the model works like this:</p>
<ul>
<li>Create the index state or re-lock (<tt>index_lock</tt>)
the mailbox on an existing index.</li>
<li>call <tt>index_refresh</tt></li>
<li>if any changes are to be made (i.e. flag updates for a store,
non-peek body fetch, expunge) then cycle through the refreshed
state map and update the records which are affected.</li>
<li>call <tt>index_unlock</tt> (unlock the underlying mailbox and
commit the statuscache changes)</li>
<p>At this point the index lock is <b>released</b> and we have not
yet generated any network traffic. Now start generating the
response.</p>
<li>if expunges are allowed, call <tt>index_tellexpunge</tt></li>
<li>call <tt>index_tellchanges</tt> to tell about all other changes</li>
<li>return any response that the command itself required</li>
</ul>
</body>
</html>
