Add the upsert and compute methods for modifying a cached entry

[tatsuya6502]

Fixes #227, #353.

This PR adds compute family-methods to the entry API. They take a closure to insert, update, or remove a value for a key depending on the current cached value.

Also bumps the version to v0.12.3.

API: future::Cache

/// Upsert (update or insert) the cached entry.
pub async fn and_upsert_with<F, Fut>(self, f: F) -> Entry<K, V>
where
    F: FnOnce(Option<Entry<K, V>>) -> Fut,
    Fut: Future<Output = V>;


/// Upsert, remove or nop (no-operation) on the cached entry.
pub async fn and_compute_with<F, Fut>(self, f: F) -> compute::CompResult<K, V>)
where
    F: FnOnce(Option<Entry<K, V>>) -> Fut,
    Fut: Future<Output = compute::Op<V>>;


/// When Ok(Op), upsert, remove or nop (no-operation) on the cached entry.
/// Otherwise return Err(E)
pub async fn and_try_compute_with<F, Fut, E>(
    self,
    f: F,
) -> Result<compute::CompResult<K, V>, E>
where
    F: FnOnce(Option<Entry<K, V>>) -> Fut,
    Fut: Future<Output = Result<compute::Op<V>, E>>,
    E: Send + Sync + 'static;

Examples

See the following examples in the examples directory of the compute-api branch:

• counter_async.rs
  • Uses the and_upsert_with method.
  • Atomically increment a cached u64.
• bounded_counter_async.rs
  • Uses the and_compute_with method.
  • Atomically increment a cached u64 but reset (remove) it when it is 2.
• append_value_async.rs
  • Uses the and_upsert_with method.
  • Atomically append an i32 to a cached Arc<RwLock<Vec<i32>>>.
• try_append_value_async.rs
  • Uses the and_try_compute_with method.
  • Atomically read an char and append to a cached Arc<RwLock<String>>, but reading can fail by EOF.

API: sync::Cache and sync::SegmentedCache

/// Upsert (update or insert) the cached entry.
pub fn and_upsert_with<F>(self, f: F) -> Entry<K, V>
where
    F: FnOnce(Option<Entry<K, V>>) -> V;


/// Upsert, remove or nop (no-operation) on the cached entry.
pub fn and_compute_with<F>(self, f: F) -> compute::CompResult<K, V>
where
    F: FnOnce(Option<Entry<K, V>>) -> compute::Op<V>;


/// When Ok(Op), upsert, remove or nop (no-operation) on the cached entry.
/// Otherwise return Err(E)
pub fn and_try_compute_with<F, E>(
    self,
    f: F,
) -> Result<compute::CompResult<K, V>, E>
where
    F: FnOnce(Option<Entry<K, V>>) -> Result<compute::Op<V>, E>,
    E: Send + Sync + 'static;

Tasks

future::Cache:

• and_upsert_with method. (upsert: insert or update)
  • Implementation.
  • Automated tests.
  • Documents.
  • Examples.
• and_compute_with method.
  • Implementation.
  • Automated tests.
  • Documents.
  • Examples.
• and_try_compute_with method.
  • Implementation.
  • Automated tests.
  • Documents.
  • Examples.

sync::Cache, sync::SegmentedCache:

• and_upsert_with method. (upsert: insert or update)
  • Implementation.
  • Automated tests.
  • Documents.
  • Examples.
• and_compute_with method.
  • Implementation.
  • Automated tests.
  • Documents.
  • Examples.
• and_try_compute_with method.
  • Implementation.
  • Automated tests.
  • Documents.
  • Examples.

[tatsuya6502]

I changed the return types of and_compute_with and and_try_compute_with methods (commit: aee7ebe).

future::Cache

-pub async fn and_compute_with<F, Fut>(self, f: F) -> (Option<Entry<K, V>>, compute::PerformedOp)
+pub async fn and_compute_with<F, Fut>(self, f: F) -> compute::CompResult<K, V>)
 where
     F: FnOnce(Option<Entry<K, V>>) -> Fut,
     Fut: Future<Output = compute::Op<V>>;

 pub async fn and_try_compute_with<F, Fut, E>(
     self,
     f: F,
-) -> Result<(Option<Entry<K, V>>, compute::PerformedOp), E>
+) -> Result<compute::CompResult<K, V>, E>
 where
     F: FnOnce(Option<Entry<K, V>>) -> Fut,
     Fut: Future<Output = Result<compute::Op<V>, E>>,
     E: Send + Sync + 'static;

sync::Cache and sync::SegmentedCache

-pub fn and_compute_with<F>(self, f: F) -> (Option<Entry<K, V>>, compute::PerformedOp)
+pub fn and_compute_with<F>(self, f: F) -> compute::CompResult<K, V>
 where
     F: FnOnce(Option<Entry<K, V>>) -> compute::Op<V>;

 pub fn and_try_compute_with<F, E>(
     self,
     f: F,
-) -> Result<(Option<Entry<K, V>>, compute::PerformedOp), E>
+) -> Result<compute::CompResult<K, V>, E>
 where
     F: FnOnce(Option<Entry<K, V>>) -> Result<compute::Op<V>, E>,
     E: Send + Sync + 'static;

[tatsuya6502]

Merging.