| 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. |