From c8ce4eacd1f67562b9ca30ff3f87b39d5e4d0bd7 Mon Sep 17 00:00:00 2001 From: Yiling-J Date: Fri, 18 Oct 2024 11:14:00 +0800 Subject: [PATCH] update readme --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 52829b5..63605be 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,11 @@ Loading cache uses [singleflight](https://pkg.go.dev/golang.org/x/sync/singlefli **Entry Pool** -Theine provides an option called `UseEntryPool` to help reduce memory allocation during heavy concurrent writes. It achieves this by reusing evicted entry structs through a sync pool. However, if you don't experience heavy concurrent writes, the sync pool may not be beneficial and could only slow things down. +Theine provides an option called `UseEntryPool` to help reduce memory allocation during heavy concurrent writes. It achieves this by reusing evicted entry structs through a `sync pool`. However, if you don't experience heavy concurrent writes, the sync pool may not be beneficial and could only slow things down. -One drawback of the entry pool is the potential for occasional race conditions within the policy. Theine sends events to the policy asynchronously using channels/buffers, and the policy decides which entries to keep or evict when the cache is full. This means that when the policy receives an UPDATE event, the related entry might already have been returned to the sync pool and reused. +One drawback of the entry pool is the potential for occasional **race conditions within the policy**. Theine sends events to the policy asynchronously using channels/buffers, and the policy decides which entries to keep or evict when the cache is full. This means that when the policy receives an UPDATE event, the related entry might already have been returned to the sync pool and reused. -For READ events, a race condition could occur under the following scenario: +For **READ** events, a race condition could occur under the following scenario: 1. Get EntryA using the API. 2. Add EntryA "get" event to the read buffer. 3. EntryA is evicted by the policy. @@ -58,12 +58,12 @@ For READ events, a race condition could occur under the following scenario: In this case, the policy may incorrectly promote EntryB. However, the likelihood of this scenario is extremely low. One potential situation where this could happen is if, after EntryA is added to the buffer, all reads stop, and only writes remain. Since the read buffer is only sent to the policy when it is full, this race condition may occur. **If a race happens for READ events, the entry might be incorrectly promoted to the head of the policy's LRU.** -For UPDATE events, a similar race condition might occur under heavy concurrent UPDATE and INSERT operations. Both update and insert actions are needed to trigger the race because inserts to the policy can cause evictions, leading to the reuse of entries by the pool. Unlike reads, the write buffer is a channel that drains proactively, not just when full. Additionally, when the policy processes UPDATE events, it checks the key again to ensure it matches. **If a race occurs for UPDATE events, the entry's cost stored in the policy might differ from the actual cost.** +For **UPDATE** events, a similar race condition might occur under heavy concurrent UPDATE and INSERT operations. Both update and insert actions are needed to trigger the race because inserts to the policy will cause evictions, leading to the reuse of entries by the pool. Unlike reads, the write buffer is a channel that drains proactively, not just when full. Additionally, when the policy processes UPDATE events, it checks the key again to ensure it matches. **If a race occurs for UPDATE events, the entry's cost stored in the policy might differ from the actual cost.** A correctness test runs as part of the CI, simulating heavy concurrent UPDATE and INSERT operations with a Zipf-distributed workload. This test verifies that the entry's policy cost (weight) matches its actual cost (weight). You can find the test here: [cache_race_test.go](https://github.com/Yiling-J/theine-go/blob/main/cache_race_test.go). -This option was introduced in Theine v0.5.1. Before this version, the entry pool was always used. Starting from v0.5.1, the `UseEntryPool` option was added and defaults to **false**. +This option was introduced in Theine v0.5.1. Before this version, the entry pool was **always used**. Starting from v0.5.1, the `UseEntryPool` option was added and **defaults to false**. **API Details**