Merge pull request #317 from moka-rs/prepare-0.12.0-beta.2

Prepare for v0.12.0-beta.2

CHANGELOG.md

@@ -3,32 +3,31 @@
 ## Version 0.12.0 (Currently Beta)
 
 **ATTENTION**: `v0.12.0` has major breaking changes on the API and internal behavior.
-Please read the [MIGRATION-GUIDE.md][migration-guide-v012] for the details.
 
-**`sync` caches are no longer enabled by default**: Please use a crate feature `sync`
-to enable it.
+- **`sync` caches are no longer enabled by default**: Please use a crate feature
+  `sync` to enable it.
 
-**No more background threads**: All cache types `future::Cache`, `sync::Cache`, and
-`sync::SegmentedCache` no longer spawn background threads.
+- **No more background threads**: All cache types `future::Cache`, `sync::Cache`, and
+  `sync::SegmentedCache` no longer spawn background threads.
 
-- The `scheduled-thread-pool` crate was removed from the dependency.
-- Because of this change, many external and internal methods of `future::Cache`
-  were converted to `async` methods. You may need to add `.await` to your code for
-  those methods.
+  - The `scheduled-thread-pool` crate was removed from the dependency.
+  - Because of this change, many private methods and some public methods under the
+    `future` module were converted to `async` methods. You may need to add `.await`
+    to your code for those methods.
 
-**Immediate notification delivery**: The `notification::DeliveryMode` enum for the
-eviction listener was removed. Now all cache types work as if the `Immediate`
-delivery mode is specified.
+- **Immediate notification delivery**: The `notification::DeliveryMode` enum for the
+  eviction listener was removed. Now all cache types behave as if the `Immediate`
+  delivery mode is specified.
 
-[migration-guide-v012]: ./MIGRATION-GUIDE.md#migrating-to-v0120-from-a-prior-version
+Please read the [MIGRATION-GUIDE.md][migration-guide-v012] for more details.
+
+[migration-guide-v012]: https://github.com/moka-rs/moka/blob/main/MIGRATION-GUIDE.md#migrating-to-v0120-from-a-prior-version
 
 ### Changed
 
-- Remove the thread pool from `sync` caches. ([#316][gh-pull-0316])
-- Remove the thread pool from `future` cache`. ([#294][gh-pull-0294])
-- Add support for `Immediate` notification delivery mode to future cache.
- ([#228][gh-issue-0228])
-- Improve async cancellation safety of `future::Cache`. ([#309][gh-pull-0309])
+- Removed the thread pool from `future` cache ([#294][gh-pull-0294]) and `sync`
+  caches ([#316][gh-pull-0316]).
+- Improved async cancellation safety of `future::Cache`. ([#309][gh-pull-0309])
 
 
 ## Version 0.11.3
@@ -702,7 +701,6 @@ The minimum supported Rust version (MSRV) is now 1.51.0 (Mar 25, 2021).
 [gh-issue-0243]: https://github.com/moka-rs/moka/issues/243/
 [gh-issue-0242]: https://github.com/moka-rs/moka/issues/242/
 [gh-issue-0230]: https://github.com/moka-rs/moka/issues/230/
-[gh-issue-0228]: https://github.com/moka-rs/moka/issues/228/
 [gh-issue-0212]: https://github.com/moka-rs/moka/issues/212/
 [gh-issue-0207]: https://github.com/moka-rs/moka/issues/207/
 [gh-issue-0162]: https://github.com/moka-rs/moka/issues/162/

Cargo.toml

@@ -12,7 +12,7 @@ repository = "https://github.com/moka-rs/moka"
 keywords = ["cache", "concurrent"]
 categories = ["caching", "concurrency"]
 readme = "README.md"
-exclude = [".circleci", ".devcontainer", ".github", ".gitpod.yml", ".vscode"]
+exclude = [".circleci", ".cirrus.yml-DISABLED", ".devcontainer", ".github", ".gitpod.yml", ".vscode"]
 build = "build.rs"
 
 [features]

MIGRATION-GUIDE.md

@@ -7,35 +7,40 @@ describes the code changes required to migrate to v0.12.0.
 
 ### Highlights v0.12
 
-**`sync` caches are no longer enabled by default**: Please use a crate feature `sync`
-to enable it.
-
-**No more background threads**: All cache types `future::Cache`, `sync::Cache`, and
-`sync::SegmentedCache` no longer spawn background threads.
-
-- The `scheduled-thread-pool` crate was removed from the dependency.
-- Because of this change, many external and internal methods of `future::Cache`
-  were converted to `async` methods. You may need to add `.await` to your code for
-  those methods.
-
-**Immediate notification delivery**: The `notification::DeliveryMode` enum for the
-eviction listener was removed. Now all cache types work as if the `Immediate`
-delivery mode is specified.
-
-- It had two variants `Immediate` and `Queued`.
-    - The former should be easier to use than other as it guarantees to preserve the
-      order of events on a given cache key.
-    - The latter would provide higher performance under heavy cache writes.
-- Now all cache types work as if the `Immediate` mode is specified.
-    - **`future::Cache`**: In earlier versions of `future::Cache`, the queued mode
-      was used. Now it works as if the immediate mode is specified.
-    - **`sync` caches**: From earlier versions of `sync::Cache` and
-      `sync::SegmentedCache`, the immediate mode is the default mode. So this change
-      should only affects those of you who are explicitly using the queued mode.
-- The queued mode was implemented by using a background thread. The queue mode was
-  removed because there is no thread pool available anymore.
-- If you need the queue mode back, please file a GitHub issue. We could provide
-  a way to use a user supplied thread pool.
+- **`sync` caches are no longer enabled by default**: Please use a crate feature
+  `sync` to enable it.
+
+- **No more background threads**: All cache types `future::Cache`, `sync::Cache`, and
+  `sync::SegmentedCache` no longer spawn background threads.
+  - The `scheduled-thread-pool` crate was removed from the dependency.
+  - Because of this change, many private methods and some public methods under the
+    `future` module were converted to `async` methods. You may need to add `.await`
+    to your code for those methods.
+
+  - Because of this change, many external and internal methods of `future::Cache`
+    were converted to `async` methods. You may need to add `.await` to your code for
+    those methods.
+
+- **Immediate notification delivery**: The `notification::DeliveryMode` enum for the
+  eviction listener was removed. Now all cache types behave as if the `Immediate`
+  delivery mode is specified.
+
+  - `DeliveryMode` enum had two variants `Immediate` and `Queued`.
+      - The former should be easier to use than other as it guarantees to preserve
+        the order of events on a given cache key.
+      - The latter did not use internal locks and would provide higher performance
+        under heavy cache writes.
+  - Now all cache types work as if the `Immediate` mode is specified.
+      - **`future::Cache`**: In earlier versions of `future::Cache`, the queued mode
+        was used. Now it behaves as if the immediate mode is specified.
+      - **`sync` caches**: From earlier versions of `sync::Cache` and
+        `sync::SegmentedCache`, the immediate mode is the default mode. So this
+        change should only affects those of you who are explicitly using the queued
+        mode.
+  - The queued mode was implemented by using a background thread. The queued mode was
+    removed because there is no thread pool available anymore.
+  - If you need the queued mode back, please file a GitHub issue. We could provide
+    a way to use a user supplied thread pool.
 
 The following sections will describe about the changes you might need to make to your
 code.
@@ -47,31 +52,32 @@ code.
 ### `sync::Cache` and `sync::SegmentedCache` v0.12
 
 1. Please use a crate feature `sync` to enable `sync` caches.
-2. Since the background threads are removed, the maintenance tasks such as removing
+2. Since the background threads were removed, the maintenance tasks such as removing
    expired entries are not executed periodically anymore.
-   - The `thread_pool_enabled` in `sync::CacheBuilder` was removed. The thread pool
-     is always disabled.
+   - The `thread_pool_enabled` method of the `sync::CacheBuilder` was removed. The
+     thread pool is always disabled.
    - See the [maintenance tasks](#the-maintenance-tasks) section for more details.
 3. The `sync` method of the `sync::ConcurrentCacheExt` trait was moved to
-   `sync::Cache` and `sync::SegmentedCache` types and renamed to `run_pending_tasks`.
+   `sync::Cache` and `sync::SegmentedCache` types. It is also renamed to
+   `run_pending_tasks`.
 4. Now `sync` caches always work as if the immediate delivery mode is specified
    for the eviction listener.
-   - In older versions, the immediate mode was the default mode. And the queued
-     mode can be optionally selected.
+   - In older versions, the immediate mode was the default mode, and the queued
+     mode could be optionally selected.
 
 ### `future::Cache` v0.12
 
 #### API changes
 
-1. `get` method is now `async fn`, so you must `await` for the result.
-2. `blocking` method was removed.
+1. The `get` method is now `async fn`, so you must `await` for the result.
+2. The `blocking` method was removed.
    - Please use async runtime's blocking API instead.
    - See the [replacing the blocking API](#replacing-the-blocking-api) section for
      more details.
-3. Now `or_insert_with_if` method of the entry API requires `Send` bound for the
+3. Now the `or_insert_with_if` method of the entry API requires `Send` bound for the
    `replace_if` closure.
-4. `eviction_listener_with_queued_delivery_mode` method of `future::CacheBuilder` was
-   removed.
+4. The `eviction_listener_with_queued_delivery_mode` method of `future::CacheBuilder`
+   was removed.
    - Please use one of the new methods instead:
      - `eviction_listener`
      - `async_eviction_listener`
@@ -83,11 +89,11 @@ code.
 
 #### Behavior changes
 
-1. Since the background threads are removed, the maintenance tasks such as removing
+1. Since the background threads were removed, the maintenance tasks such as removing
    expired entries are not executed periodically anymore.
    - See the [maintenance tasks](#the-maintenance-tasks) section for more details.
-2. Now `future::Cache` always works as if the immediate delivery mode is specified
-   for eviction listener.
+2. Now `future::Cache` always behaves as if the immediate delivery mode is specified
+   for the eviction listener.
    - In older versions, the queued delivery mode was used.
 
 #### Replacing the blocking API
@@ -97,8 +103,8 @@ blocking API instead.
 
 **Tokio**
 
-1. Call `tokio::runtime::Handle::current()` in async context to obtain a handle to
-   the current Tokio runtime.
+1. Call the `tokio::runtime::Handle::current()` method in async context to obtain a
+   handle to the current Tokio runtime.
 2. From outside async context, call cache's async function using `block_on` method of
    the runtime.
 
@@ -133,7 +139,7 @@ async fn main() {
 
 **async-std**
 
-- From outside async context, call cache's async function using
+- From outside async context, call cache's async function using the
   `async_std::task::block_on` method.
 
 ```rust
@@ -166,16 +172,14 @@ async fn main() {
 
 #### Updating the eviction listener
 
-- The `notification::DeliveryMode` for eviction listener was changed from `Queued` to
-  `Immediate`.
-- `eviction_listener_with_queued_delivery_mode` method of `future::CacheBuilder` was
-  removed. Please use one of the new methods `eviction_listener` or
-  `async_eviction_listener` instead.
+The `eviction_listener_with_queued_delivery_mode` method of `future::CacheBuilder`
+was removed. Please use one of the new methods `eviction_listener` or
+`async_eviction_listener` instead.
 
 ##### `eviction_listener` method
 
-`eviction_listener` takes the same closure as the old method. If you do not need to
-`.await` anything in the eviction listener, use this method.
+The `eviction_listener` method takes the same closure as the old method. If you do
+not need to `.await` anything in the eviction listener, use this method.
 
 This code snippet is borrowed from [an example][listener-ex1] in the document of
 `future::Cache`:
@@ -196,7 +200,7 @@ let cache = Cache::builder()
 
 ##### `async_eviction_listener` method
 
-`async_eviction_listener` takes a closure that returns a `Future`. If you need to
+The `async_eviction_listener` takes a closure that returns a `Future`. If you need to
 `await` something in the eviction listener, use this method. The actual return type
 of the closure is `notification::ListenerFuture`, which is a type alias of
 `Pin<Box<dyn Future<Output = ()> + Send>>`. You can use the `boxed` method of
@@ -263,7 +267,7 @@ These maintenance tasks include:
    wheels.
 3. When cache's max capacity is exceeded, remove least recently used (LRU) entries.
 4. Remove expired entries.
-5. Find and remove the entries that have been invalidated by `invalidate_all` or
+5. Find and remove the entries that have been invalidated by the `invalidate_all` or
    `invalidate_entries_if` methods.
 6. Deliver removal notifications to the eviction listener. (Call the eviction
    listener closure with the information about the evicted entry)
@@ -273,26 +277,26 @@ conditions is met:
 
 Cache Methods:
 
-- All cache write methods: `insert`, `get_with`, `invalidate`, etc.
+- All cache write methods: `insert`, `get_with`, `invalidate`, etc., except for
+  `invalidate_all` and `invalidate_entries_if`.
 - Some of the cache read methods: `get`
 - `run_pending_tasks` method, which executes the pending maintenance tasks
   explicitly.
 
 Conditions:
 
 - When one of the numbers of pending read and write recordings exceeds the threshold.
-    - It is currently hard-coded to 64 items.
+    - The threshold is currently hard-coded to 64 items.
 - When the time since the last execution of the maintenance tasks exceeds the
   threshold.
-    - It is currently hard-coded to 300 milliseconds.
-
+    - The threshold is currently hard-coded to 300 milliseconds.
 
 #### `run_pending_tasks` method
 
 You can execute the pending maintenance tasks explicitly by calling the
 `run_pending_tasks` method. This method is available for all cache types.
 
-Note that cache read methods such as `get`, `get_with` and `contains_key` never
+Note that cache read methods such as the `get`, `get_with` and `contains_key` never
 return expired entries although they are not removed immediately from the cache when
 they expire. You will not need to call `run_pending_tasks` method to remove expired
-entries unless you want to remove them immediately (e.g. to free some memory).
+entries unless you want to remove them immediately (e.g. to free some resources).

README.md

@@ -532,15 +532,16 @@ $ cargo +nightly -Z unstable-options --config 'build.rustdocflags="--cfg docsrs"
 - [x] Variable (per-entry) expiration, using a hierarchical timer wheel.
   (`v0.11.0` via [#248][gh-pull-248])
 - [ ] Cache statistics. (Hit rate, etc.)
-- [x] Remove background threads. (`v0.12.0` via [#294][gh-pull-294] and [#???][gh-pull-qqq])
+- [x] Remove background threads. (`v0.12.0` via [#294][gh-pull-294] and
+  [#316][gh-pull-316])
 - [ ] Upgrade TinyLFU to Window-TinyLFU. ([details][tiny-lfu])
 
 [gh-pull-024]: https://github.com/moka-rs/moka/pull/24
 [gh-pull-105]: https://github.com/moka-rs/moka/pull/105
 [gh-pull-145]: https://github.com/moka-rs/moka/pull/145
 [gh-pull-248]: https://github.com/moka-rs/moka/pull/248
 [gh-pull-294]: https://github.com/moka-rs/moka/pull/294
-[gh-pull-qqq]: https://github.com/moka-rs/moka/pull/qqq
+[gh-pull-316]: https://github.com/moka-rs/moka/pull/316
 
 
 ## About the Name