Instance manager that shards instances across multiple Spex.InstanceManager.Server processes.

This manager hashes each instance identifier and routes operations to one of several server shards. It is useful when you want to reduce contention versus a single-manager setup while preserving the same high-level API.

This module is designed to be added directly to your supervision tree:

children = [
  {Spex.InstanceManager.DistributedInstanceManager,
   distribution_factor: 8,
   impl_models_dir: "./spex_impl_models",
   dets_dir: "./spex_dets"}
]

You may pass options at startup or configure them in application config.

Configuration

This manager accepts one distribution-specific option plus server options forwarded to each shard (Spex.InstanceManager.Server.server_opt()).

• :distribution_factor (pos_integer()) Number of server shards. Default: 4. Must be a positive integer; otherwise start_link/1 raises ArgumentError.

Forwarded server options:

• :impl_models_dir (String.t()) Directory from which .spex impl models are loaded. Each shard loads from the same directory at startup. Default: "./spex_impl_models".

• :dets_dir (String.t()) Base directory for shard DETS files. Default: "./spex_dets".

• :check_transition_timeouts_on_start? (boolean()) Enables startup timeout checks per shard. Default: true.

• :prune_interval (timeout()) Periodic pruning interval per shard. Default: to_timeout(%Duration{hour: 6}).

Pruning semantics per shard:

• one prune pass is always executed immediately on shard startup,
• when :prune_interval != :infinity, additional periodic prune passes are scheduled,
• when :prune_interval == :infinity, no periodic passes are scheduled after the initial startup pass.

Internal shard detail:

• :dets_table is set per shard by this module (Spex.InstanceManager.DistributedInstanceManager.Server_<n>), so callers should not provide it.

Option Resolution Order

For forwarded server options, each shard resolves values in this order:

1. option passed to this manager at startup,
2. application environment key under :spex,
3. server default.

Routing Semantics

Instance routing is deterministic:

• hash = :erlang.phash2(instance_identifier)
• shard index = rem(hash, distribution_factor) + 1

All operations for a given instance identifier are routed to the same shard.

Methods that aggregate globally (all_instances/0, all_instances/1, delete_instances/1, all_impl_models/0) query all shards and combine the results.

Application Config Example

config :spex,
  impl_models_dir: "./priv/spex_impl_models",
  dets_dir: "./priv/spex_dets",
  check_transition_timeouts_on_start?: true,
  prune_interval: :timer.hours(6)