Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve MapRef docs #3829

Merged
merged 7 commits into from
Sep 26, 2023
Merged

Improve MapRef docs #3829

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2b05156
Improve MapRef docs
BalmungSan Sep 15, 2023
cc0bc86
Re-word the contention point
BalmungSan Sep 15, 2023
b72aaec
Add simple MapRef docs page
BalmungSan Sep 15, 2023
0385b34
Update docs/std/mapref.md
BalmungSan Sep 15, 2023
58a0ffc
Apply review comments
BalmungSan Sep 24, 2023
53016c8
Merge branch 'series/3.5.x' into mapref-docs
djspiewak Sep 25, 2023
33c93b1
Fix mdoc compilation error
BalmungSan Sep 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion kernel/shared/src/main/scala/cats/effect/kernel/Ref.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,11 @@ import cats.syntax.all._
* mutable data as `AtomicReference#compareAndSet` and friends are dependent upon object
* reference equality.
*
* See also `cats.effect.std.AtomicCell` class from `cats-effect-std` for an alternative.
* See also `cats.effect.std.AtomicCell` class from `cats-effect-std` for an alternative that
* ensures exclusive access and effectual updates.
*
* If your contents are an immutable `Map[K, V]`, and all your operations are per-key, consider
* using `cats.effect.std.MapRef`.
*/
abstract class Ref[F[_], A] extends RefSource[F, A] with RefSink[F, A] {

Expand Down
8 changes: 6 additions & 2 deletions std/shared/src/main/scala/cats/effect/std/MapRef.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,12 @@ import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.atomic.AtomicBoolean

/**
* This is a total map from K to Ref[F, V]. This allows us to use the Ref API backed by a
* ConcurrentHashMap or similar.
* This is a total map from `K` to `Ref[F, V]`.
*
* It is conceptually similar to a `Ref[F, Map[K, V]]`, but with better ergonomics when working
* on a per key basis. It also has less contention since the key-value pairs are sharded; thus
BalmungSan marked this conversation as resolved.
Show resolved Hide resolved
* multiple concurrent updates may be performed independently to each other. Note, however, that
* it does not support atomic updates to multiple keys.
*/
trait MapRef[F[_], K, V] extends Function1[K, Ref[F, V]] {

Expand Down