Debian Codegraph @

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

raw
1 .. _imap-developer-guidance-namelocks:
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: Namelocks
8 ============================
9
10 Intro
11 -----
12
13 Name locks are an addition to the cyrus internals to address a range of
14 race conditions and complexities. These ills are most easily avoided by
15 ensuring that only one process can do certain operations at once. Name
16 locks also mean crashes can't leave the mailbox "broken" forever.
17
18 Unfortunately, locks can't be retained over a rewrite-rename cycle, and
19 every meta file in a regular mailbox gets rewritten upon occasion. Even
20 cyrus.header gets a rewrite when a new userflag is added.
21
22 The "RESERVED FLAG" method of handling mailbox creation is a nasty
23 brutish method that breaks on process crashes, causing a full
24 mailboxes.db sweep to be necessary on restart, and making that name
25 unusable until the entire server is restarted. It's also unusable for
26 serialisation of operations without making the mailbox "disappear" to
27 other clients.
28
29 Mailbox names are supposed to be exclusive per server, not just per
30 partition, so any lock has to apply to the entire server.
31
32 **MURDER Considerations:** Due to the way the mupdate protocol works,
33 RESERVED records are still created over mupdate. This sucks, and a
34 better way would be to support an "EXCLUSIVE CREATE" command, where the
35 create only succeeds if the record doesn't already exist. Then a task
36 could create the mailbox on the local server and retain an exclusive
37 namelock while trying to assert the name on the mupdate server. If this
38 failed (someone else got in first) then the mailbox could be cleaned up
39 locally before releasing the exclusive namelock, meaning other users on
40 the local server would never see it existing.
41
42 Implementation
43 --------------
44
45 It's a simple matter of having a file under $configdirectory/lock - in a
46 directory tree using the same hashing structure as the mailbox tree.
47 This directory can be symlinked or mounted to a tmpfs since the locks
48 need not persist across restarts. Due to race conditions while cleaning
49 up, the easiest approach is to only ever delete lock files during
50 restart, so the unlock code doesn't try to remove them. Lock files are
51 zero byte in size, and are locked using the flock or fcntl primitives
52 used by the rest of cyrus.
53
54 API
55 ---
56
57 Lock types:
58
59 - LOCK\_SHARED - shared lock on the name. Required whenever you have an
60 open mailbox with that name
61 - LOCK\_EXCLUSIVE - exclusive lock on the name. Required to create or
62 finish deleting a mailbox, and required when repacking the
63 cyrus.index and cyrus.cache files.
64 - LOCK\_NONBLOCKING - attempt to take an exclusive lock on the name,
65 but if it's not available, return immediately with r ==
66 IMAP\_MAILBOX\_LOCKED rather than blocking until the lock is
67 available.
68
69 The ``mboxname`` is always an **internal name**, so convert it first.
70
71 Example:
72 ~~~~~~~~
73
74 ::
75
76 struct mboxlock *lock = NULL;
77 int locktype = LOCK_SHARED; /* or LOCK_EXCLUSIVE or LOCK_NONBLOCKING */
78
79 r = mboxname_lock("user.brong", &lock, locktype);
80 if (!r) {
81 do_stuff();
82 mboxname_release(&lock);
83 }
84
85 If mboxname\_lock fails, lock will remain NULL. It should always be
86 initialised to NULL before being passed to mailbox\_lock. It will be set
87 back to NULL by mboxname\_release.
88
89 Re-locking considerations
90 ~~~~~~~~~~~~~~~~~~~~~~~~~
91
92 It is not possible to hold multiple locks to the same name within the
93 same process. If you call mboxname\_lock with the same name within a
94 process, and the **same locktype** then a reference counter is
95 incremented and the same lock is returned. If you use a **different
96 locktype** (i.e. one shared, the other exclusive. Non-blocking is
97 considered exclusive for this test) then IMAP\_MAILBOX\_LOCKED will be
98 returned to avoid breaking the locking semantics. This is a restriction
99 of the underlying fcntl/flock subsystem.
100
101 On the way out, the reference counter is decremented with each release
102 and the lock isn't freed until the counter gets back to zero.