Function notmuch_sys::notmuch_message_freeze [−] [src]

pub unsafe extern "C" fn notmuch_message_freeze(
    message: *mut notmuch_message_t
) -> notmuch_status_t

Freeze the current state of 'message' within the database.

This means that changes to the message state, (via notmuch_message_add_tag, notmuch_message_remove_tag, and notmuch_message_remove_all_tags), will not be committed to the database until the message is thawed with notmuch_message_thaw.

Multiple calls to freeze/thaw are valid and these calls will "stack". That is there must be as many calls to thaw as to freeze before a message is actually thawed.

The ability to do freeze/thaw allows for safe transactions to change tag values. For example, explicitly setting a message to have a given set of tags might look like this:

notmuch_message_freeze (message);

notmuch_message_remove_all_tags (message);

for (i = 0; i < NUM_TAGS; i++)
    notmuch_message_add_tag (message, tags[i]);

notmuch_message_thaw (message);

With freeze/thaw used like this, the message in the database is guaranteed to have either the full set of original tag values, or the full set of new tag values, but nothing in between.

Imagine the example above without freeze/thaw and the operation somehow getting interrupted. This could result in the message being left with no tags if the interruption happened after notmuch_message_remove_all_tags but before notmuch_message_add_tag.

Return value:

notmuch_status_t::SUCCESS: Message successfully frozen.

notmuch_status_t::READ_ONLY_DATABASE: Database was opened in read-only mode so message cannot be modified.