Debian Codegraph @

doc/html/_sources/imap/developer/guidance/locking.rst.txt

raw
1 .. _imap-developer-guidance-locking:
2
3 .. Note: This document was converted from the original by Nic Bernstein
4 (Onlight). Any formatting mistakes are my fault and not the
5 original author's.
6
7 Cyrus IMAP Server: Locking
8 ==========================
9
10 Mailboxes
11 ---------
12
13 For mailboxes, we lock in this order:
14
15 * Mailbox Namelock (shared) <== possibly reversible with
16 conversationsdb
17 * user conversations db
18 * cyrus.index
19
20 If you want to do any mailboxes.db transactions, they need to open
21 and close without changing any mailbox locking during the transaction.
22
23 Likewise seen and statuscache are always done without changing mailbox
24 locking during their transaction.
25
26 Annotations databases are a mess.
27
28 Xapian
29 ------
30
31 * Xapian per-user NAMELOCK (shared or exclusive)
32 * xapianactive file lock (shared or exclusive)
33
34 Shared namelock holds the following invariants:
35
36 * xapianactive file contents are not changed
37 * directories mentioned in xapianactive are not cleaned up
38
39 Xapianactive exclusive lock holds the following invariants:
40
41 * owner may write to first database mentioned in xapianactive
42
43 Xapianactive shared lock holds:
44
45 * all databases in xapianactive are readable and a consistent
46 read can be made across all of them, even with multiple requests
47 while the lock is held.
48
49
50 Locking orders
51 ++++++++++++++
52
53 SHARED case:
54
55 * user conversations db <=== possibly reversible with SHARED xapian
56 namelock
57 * SHARED xapian namelock
58 * xapianactive lock (shared to search, exclusive to write)
59 * cyrus.index may be locked either side of the xapianactive lock,
60 because the conversationsdb lock protects it from races.
61
62 EXCLUSIVE case:
63
64 * EXCLUSIVE xapian namelock
65 That's it. While you've got this, you can add or delete items from
66 the xapianactive file, and delete paths on disk for directories
67 that you have removed (either during or after locking). No other
68 locks are permitted.
69
70
71 If you hold a SHARED xapian namelock, you may write to a .NEW folder
72 for a xapianactive entry that you created without taking any additional
73 locks, because nothing can clean it under you, and nothing else can
74 read it. This is how the repack case works.
75
76 Lock lifetime
77 -------------
78
79 * Shared mailbox namelock:
80 * possibly hours
81 * conversations db and below
82 * short as possible
83
84 Mailbox namelock holds the following invariants:
85
86 * cyrus.index may not be repacked, however flags and modseqs may be
87 updated
88 * cyrus.annotations records may change (kind of buggy and bad,
89 ideally we'd always write new ones if we changed them and keep the
90 old ones)
91 * cyrus.cache may be appended, but never changed
92 * spool files may not be deleted (already can't be changed)