dgen (DGen v0.3.0)

Copy Markdown View Source

Internal helpers for the dgen_server call/reply protocol.

This module implements the client-side call flow: pushing a call request onto the durable queue, waiting for the reply via a watch, and cleaning up reply keys on timeout.

Reply payloads are stored using the codec's chunked term encoding so that replies can exceed the single-value size limit. The watch is placed on the first chunk key; the client always reads via get_range.

Call Request Flow

  1. The caller invokes dgen_server:call/3 which delegates to call/4.
  2. A call request is pushed onto the durable queue via push_call/5, which writes noreply as a chunked term under the from-key and sets a watch on the first chunk key.
  3. The caller blocks in await_call_reply/4 until the watch fires or the timeout expires.
  4. A consumer processes the request and writes {reply, Reply} as a chunked term under the from-key.
  5. The watch fires, the caller reads and clears the chunked reply.
  6. On timeout the caller clears the chunked reply keys to avoid leaks.

Summary

Types

from()
tuid()

Functions

call(Module, Server, Request, Timeout)

Sends a synchronous call through the durable queue and waits for the reply.

get_from(WaitingKey, Ref)

Builds a from-key tuple from a waiting key and a unique ref.

get_waiting_key(Tuple)

Appends the <<"c">> waiting-key tag to a tuid tuple.

push_call(Td, Tuid, Quid, Request, WatchTo, Options)

Pushes a call request onto the durable queue.

push_call/7

Like push_call/6 but records Attempts as the initial attempt count in the message envelope. Pass a non-zero value when the call has already failed at least once (e.g. after an inline execution attempt) so the dead-letter threshold accounts for all failures.

Types

from()

-type from() :: tuple().

tuid()

-type tuid() :: tuple().

Functions

call(Module, Server, Request, Timeout)

-spec call(module(), gen_server:server_ref(), term(), timeout()) -> term().

Sends a synchronous call through the durable queue and waits for the reply.

Module is the gen_server-compatible module used to send the initial message (typically gen_server). On timeout, the reply keys are cleared to prevent durable key leaks.

get_from(WaitingKey, Ref)

-spec get_from(dgen_backend:tuple_key(), reference()) -> from().

Builds a from-key tuple from a waiting key and a unique ref.

The key includes a system-time timestamp (seconds) so that abandoned call keys can be garbage-collected using a time-based heuristic. Key structure: {WaitingKey..., Timestamp, term_to_binary(Ref)}.

get_waiting_key(Tuple)

-spec get_waiting_key(tuid()) -> dgen_backend:tuple_key().

Appends the <<"c">> waiting-key tag to a tuid tuple.

push_call(Td, Tuid, Quid, Request, WatchTo, Options)

-spec push_call(term(), tuid(), dgen_queue:quid(), term(), pid(), list()) ->
                   {from(), dgen_backend:future()}.

Pushes a call request onto the durable queue.

Writes noreply as a chunked term under the from-key prefix, sets a watch on the first chunk key directed to WatchTo, and enqueues the request. Returns {From, Watch} where From is the from-key tuple.

push_call/7

-spec push_call(term(), tuid(), dgen_queue:quid(), term(), pid(), list(), non_neg_integer()) ->
                   {from(), dgen_backend:future()}.

Like push_call/6 but records Attempts as the initial attempt count in the message envelope. Pass a non-zero value when the call has already failed at least once (e.g. after an inline execution attempt) so the dead-letter threshold accounts for all failures.