diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b863a0f..52363e05 100644 --- a/CHANGELOG.md +++ b/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/ diff --git a/Cargo.toml b/Cargo.toml index 5e22ecc8..9b76d3d4 100644 --- a/Cargo.toml +++ b/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] diff --git a/MIGRATION-GUIDE.md b/MIGRATION-GUIDE.md index 6cf15c66..199b690e 100644 --- a/MIGRATION-GUIDE.md +++ b/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 + 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,7 +277,8 @@ 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. @@ -281,18 +286,17 @@ Cache Methods: 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). diff --git a/README.md b/README.md index 828b625b..fb3568dd 100644 --- a/README.md +++ b/README.md @@ -532,7 +532,8 @@ $ 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 @@ -540,7 +541,7 @@ $ cargo +nightly -Z unstable-options --config 'build.rustdocflags="--cfg docsrs" [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