Cyrus IMAP Server: Namelocks

Intro

Name locks are an addition to the cyrus internals to address a range of race conditions and complexities. These ills are most easily avoided by ensuring that only one process can do certain operations at once. Name locks also mean crashes can’t leave the mailbox “broken” forever.

Unfortunately, locks can’t be retained over a rewrite-rename cycle, and every meta file in a regular mailbox gets rewritten upon occasion. Even cyrus.header gets a rewrite when a new userflag is added.

The “RESERVED FLAG” method of handling mailbox creation is a nasty brutish method that breaks on process crashes, causing a full mailboxes.db sweep to be necessary on restart, and making that name unusable until the entire server is restarted. It’s also unusable for serialisation of operations without making the mailbox “disappear” to other clients.

Mailbox names are supposed to be exclusive per server, not just per partition, so any lock has to apply to the entire server.

MURDER Considerations: Due to the way the mupdate protocol works, RESERVED records are still created over mupdate. This sucks, and a better way would be to support an “EXCLUSIVE CREATE” command, where the create only succeeds if the record doesn’t already exist. Then a task could create the mailbox on the local server and retain an exclusive namelock while trying to assert the name on the mupdate server. If this failed (someone else got in first) then the mailbox could be cleaned up locally before releasing the exclusive namelock, meaning other users on the local server would never see it existing.

Implementation

It’s a simple matter of having a file under $configdirectory/lock - in a directory tree using the same hashing structure as the mailbox tree. This directory can be symlinked or mounted to a tmpfs since the locks need not persist across restarts. Due to race conditions while cleaning up, the easiest approach is to only ever delete lock files during restart, so the unlock code doesn’t try to remove them. Lock files are zero byte in size, and are locked using the flock or fcntl primitives used by the rest of cyrus.

API

Lock types:

  • LOCK_SHARED - shared lock on the name. Required whenever you have an open mailbox with that name

  • LOCK_EXCLUSIVE - exclusive lock on the name. Required to create or finish deleting a mailbox, and required when repacking the cyrus.index and cyrus.cache files.

  • LOCK_NONBLOCKING - attempt to take an exclusive lock on the name, but if it’s not available, return immediately with r == IMAP_MAILBOX_LOCKED rather than blocking until the lock is available.

The mboxname is always an internal name, so convert it first.

Example:

struct mboxlock *lock = NULL;
int locktype = LOCK_SHARED; /* or LOCK_EXCLUSIVE or LOCK_NONBLOCKING */

r = mboxname_lock("user.brong", &lock, locktype);
if (!r) {
    do_stuff();
    mboxname_release(&lock);
}

If mboxname_lock fails, lock will remain NULL. It should always be initialised to NULL before being passed to mailbox_lock. It will be set back to NULL by mboxname_release.

Re-locking considerations

It is not possible to hold multiple locks to the same name within the same process. If you call mboxname_lock with the same name within a process, and the same locktype then a reference counter is incremented and the same lock is returned. If you use a different locktype (i.e. one shared, the other exclusive. Non-blocking is considered exclusive for this test) then IMAP_MAILBOX_LOCKED will be returned to avoid breaking the locking semantics. This is a restriction of the underlying fcntl/flock subsystem.

On the way out, the reference counter is decremented with each release and the lock isn’t freed until the counter gets back to zero.