docs: document bucket lifetime and watch semantics - #24
Merged
Conversation
None of this was written down anywhere: that a bucket's table dies with its owning process and is not repopulated, that bucket names share one application-wide namespace, that a notification says a key changed but not what it changed to, and that :ets_options replaces the defaults rather than merging with them. Also documents default_ets_options/0, which is how to extend those defaults instead of replacing them.
Drops the implementation detail from the new sections — ETS ownership, the registry, why a value can move on between the message and the read — and keeps only what a caller has to know. Also fixes "Unsubsribes" in unwatch_key/2 and unwatch_all/1, and notes that all/1 returns pairs in no defined order.
- add a link to the docs on hexdocs, which was missing entirely
- lead with the supervision tree instead of the bare start_link, matching
the moduledoc and the fact that a bucket is a cache
- document {:deleted, bucket, key}, which was absent although delete/2
has always sent it, and mention unwatch_key/2 and unwatch_all/1
- add parens to IO.puts and use sentence case for headings, so the
examples match the style the project formats its code with
"Key-value store" is the established term; "storage" reads as the abstract mass noun. Changes the package description, the moduledoc and the README together so all three stay in sync.
Replaces the plain documentation link with the badges the ecosystem uses, so the current version and the docs are reachable from the top of the README. Also adds a Changelog link to the package metadata, which only pointed at GitHub before.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents behaviour that already exists but was written down nowhere. No code changes.
## Buckets— a bucket's ETS table dies with its owning process and is never repopulated, so a bucket is a cache and not a store. Also that bucket names share one application-wide registry, which matters for anything usingRkvinside a library.## Watching changes— a notification says that a key changed, not what it changed to, so it has to be followed by a read. Because reads and writes bypass the owning process, the value can move on again before that read lands: you converge on the latest value but cannot reconstruct the sequence of changes. Also that one message arrives per subscription, matchingPhoenix.PubSub, so watching both a key and its bucket delivers two.:ets_options— replaces the defaults rather than merging with them, which is a one-time footgun worth stating.default_ets_options/0is now documented as the way to extend them, with a verified example. The option docs also now mention theArgumentErrorfrom #23.Checked with
mix docs(no warnings) and thedefault_ets_options() ++ [:compressed]example was run before being documented.