Bedrock.ControlPlane.Distributor.Placeholder (bedrock v0.7.0)

View Source

The coverage placeholder: a process that speaks the materializer read API and parks reads for uncovered shard tags, bounded by min(caller timeout, hold_ms), shedding {:error, :unavailable} — which clients already classify as retryable — when coverage does not arrive in time.

An honest note on what parking buys whom: the transaction builder passes its fetch timeout (50ms) as the caller timeout, so for repo traffic the effective park is ~50ms per attempt and the caller's own clock usually expires first — the REPO's retry-with-backoff loop does the actual waiting, and this process serves as a crash-absorbing, demand-signaling stall (no noproc storms, gaps visible in the keyspace, demand deduped per tag). The full hold_ms park is reachable only by direct materializer callers with generous or absent timeouts. Parked entries self-expire; replies to dead callers are no-ops.

Addressing is the settled option 2 (bedrock-q67.21): the placeholder IS a materializer ref — an ordinary MEMBER of the shard's set, one that parks rather than serves. The distributor publishes materializers/<tag>/<placeholder_worker_id> = distributor_node for uncovered tags, and the placeholder registers under cluster.otp_name_for_worker(placeholder_worker_id) — so proxies and clients need no special case at all; coverage gaps are visible in the keyspace like any other assignment. A corollary: a restarted placeholder re-registers the same name on the same node, so restarts need no republication.

When the distributor delivers {:covered, tag, ref} the tag's parked requests drain by re-issue; {:coverage_failed, tag, reason} sheds.

Summary

Functions

The default maximum time a request may be parked awaiting coverage.

Notifies the placeholder that recruitment for a shard tag failed: parked requests shed {:error, :unavailable} and the demand dedupe clears so a later request re-triggers recruitment.

Notifies the placeholder that a shard tag is now covered by a live materializer. Parked requests for the tag are drained by re-issuing them against the materializer; subsequent requests forward to it.

Notifies the placeholder that a shard tag's materializer has died and the tag is uncovered again: subsequent requests park and re-demand coverage instead of forwarding to the dead ref.

The reserved worker id placeholder entries carry in the keyspace.

Types

ref()

@type ref() :: pid() | atom() | {atom(), node()}

Functions

default_hold_ms()

@spec default_hold_ms() :: pos_integer()

The default maximum time a request may be parked awaiting coverage.

notify_coverage_failed(placeholder, tag, reason)

@spec notify_coverage_failed(ref(), Bedrock.range_tag(), reason :: term()) :: :ok

Notifies the placeholder that recruitment for a shard tag failed: parked requests shed {:error, :unavailable} and the demand dedupe clears so a later request re-triggers recruitment.

notify_covered(placeholder, tag, materializer)

@spec notify_covered(ref(), Bedrock.range_tag(), materializer :: ref()) :: :ok

Notifies the placeholder that a shard tag is now covered by a live materializer. Parked requests for the tag are drained by re-issuing them against the materializer; subsequent requests forward to it.

notify_uncovered(placeholder, tag)

@spec notify_uncovered(ref(), Bedrock.range_tag()) :: :ok

Notifies the placeholder that a shard tag's materializer has died and the tag is uncovered again: subsequent requests park and re-demand coverage instead of forwarding to the dead ref.

start_link(opts)

worker_id()

@spec worker_id() :: String.t()

The reserved worker id placeholder entries carry in the keyspace.