replace

Returns a ReplaceBuilder that will perform a transactional cache replacement.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

let current = replace(CacheKey::from_static(b"my_key")).begin()?;

let contents = if let Some(found) = current.existing_object() {
    todo!("create replacement object from existing")
} else {
    b"my cached object"
};

let mut writer = current
    .surrogate_keys(["my_key"])
    .known_length(contents.len() as u64)
    .execute(Duration::from_secs(3600))?;
writer.write_all(contents)?;
writer.finish()?;

A cache replacement has two phases. In the first phase following ReplaceBuilder::begin() you have access to an existing object, if one exists, including its metadata. In the second phase following Replace::execute() you write the replacement object. You may use the existing object from the first phase to determine the metadata arguments for the replacement object.

The ReplaceStrategy chosen controls whether one replace will wait for another and whether or not a lookup request needs to wait for a the replace to start writing the replacement object.

When replacing an object the request headers used to lookup an existing object provided by ReplaceBuilder::header() or ReplaceBuilder::header_values() should match the request headers used to write the replacement object provided by Replace::header() or Replace::header_values(). Additionally if you use a lookup or insert to create an object then later replace it the Replace::vary_by() should match. If the header or vary values are different between the existing object and the replacement object other requests looking up the object may not be able to find the replacement object.