TypeSafeSDK.OTP.Server behaviour (TypeSafeSDK v0.4.0)

Copy Markdown View Source

Bounded OTP facade for asynchronous TypeSafe evaluations inside a GenServer.

use TypeSafeSDK.OTP.Server keeps ordinary GenServer callbacks in the caller module and adds one callback, handle_evaluation/3. Return {:evaluate, {tag, state, questions}, inner_state} (or the four-element form with per-request options) from a callback to start an evaluation without blocking the server. The eventual {:ok, response} / {:error, error} result is delivered to handle_evaluation/3 with the same opaque tag.

This module deliberately does not start a global supervisor or own an HTTP runtime. Callers provide a Task.Supervisor from their application tree and a normal TypeSafeSDK.Client. max_in_flight bounds pending evaluations for the server. TypeSafeSDK still delegates HTTP, retries and physical cancellation to Pristine.

The wrapper scopes every request with its own private Pristine.Cancellation token. When the caller supplies a cancellation token, a temporary watcher mirrors caller cancellation into the private token without mutating caller-owned state. On server shutdown the private token is cancelled before the local task is stopped.

Summary

Types

async_result(state)

Return values accepted from asynchronous delegated callbacks.

call_result(state)

Return values accepted from handle_call/3.

evaluation_request()

A request started by a callback without blocking the server.

tag()

An opaque correlation term returned unchanged to handle_evaluation/3.

Callbacks

code_change(arg1, term, term)
handle_call(term, from, term)
handle_cast(term, term)
handle_continue(term, term)
handle_evaluation(arg1, tag, term)
handle_info(term, term)
init(term)
terminate(term, term)

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

start_link(module, opts)

Start a wrapped module.

Types

async_result(state)

@type async_result(state) ::
  {:evaluate, evaluation_request(), state}
  | {:noreply, state}
  | {:noreply, state, timeout() | :hibernate | {:continue, term()}}
  | {:stop, term(), state}

Return values accepted from asynchronous delegated callbacks.

call_result(state)

@type call_result(state) ::
  async_result(state)
  | {:reply, term(), state}
  | {:reply, term(), state, timeout() | :hibernate | {:continue, term()}}
  | {:stop, term(), term(), state}

Return values accepted from handle_call/3.

evaluation_request()

@type evaluation_request() ::
  {tag(), term(), term()} | {tag(), term(), term(), keyword()}

A request started by a callback without blocking the server.

tag()

@type tag() :: term()

An opaque correlation term returned unchanged to handle_evaluation/3.

Callbacks

code_change(arg1, term, term)

(optional) 
@callback code_change(term() | {:down, term()}, term(), term()) ::
  {:ok, term()} | {:error, term()}

handle_call(term, from, term)

(optional) 
@callback handle_call(term(), GenServer.from(), term()) :: call_result(term())

handle_cast(term, term)

(optional) 
@callback handle_cast(term(), term()) :: async_result(term())

handle_continue(term, term)

(optional) 
@callback handle_continue(term(), term()) :: async_result(term())

handle_evaluation(arg1, tag, term)

@callback handle_evaluation({:ok, term()} | {:error, term()}, tag(), term()) ::
  async_result(term())

handle_info(term, term)

(optional) 
@callback handle_info(term(), term()) :: async_result(term())

init(term)

@callback init(term()) ::
  {:ok, term()}
  | {:ok, term(), timeout() | :hibernate | {:continue, term()}}
  | {:stop, term()}
  | :ignore

terminate(term, term)

(optional) 
@callback terminate(term(), term()) :: term()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_link(module, opts)

@spec start_link(module(), keyword()) :: GenServer.on_start()

Start a wrapped module.

Required options are :client and :task_supervisor. Optional wrapper options are :init_arg, :max_in_flight (default 32), and :evaluation_options. Standard GenServer start options such as :name are also accepted.