# `Nebulex.Distributed`
[🔗](https://github.com/elixir-nebulex/nebulex_distributed/blob/v3.2.3/lib/nebulex/distributed.ex#L1)

Distributed caching adapters for [Nebulex](https://hexdocs.pm/nebulex).

This package provides adapters for building distributed cache topologies
on top of Nebulex. Each adapter wraps a local cache adapter (e.g.,
`Nebulex.Adapters.Local`) and adds a distributed layer on top of it.

## Adapters

  * `Nebulex.Adapters.Partitioned` - Partitioned cache topology where
    data is sharded across cluster nodes using consistent hashing.
    Each node owns a subset of the keyspace, providing linear
    scalability and single-hop point-to-point operations.

  * `Nebulex.Adapters.Multilevel` - Multi-level (near) cache topology
    with a hierarchy of cache layers (e.g., L1 local + L2 distributed).
    Reads check levels in order for fast local hits with fallback to
    slower shared layers. Writes use a write-through policy.

  * `Nebulex.Adapters.Coherent` - Local cache with distributed
    invalidation via `Nebulex.Streams`. Each node maintains its
    own independent local cache for maximum read performance;
    entries are only present on nodes that have fetched them.
    Writes broadcast invalidation events across the cluster so
    other nodes delete stale entries and fetch fresh data on
    the next read.

  * `Nebulex.Adapters.Replicated` - Push-based replicated cache
    topology where writes are eagerly replicated to all nodes via
    buffered RPC.

## Choosing an Adapter

| Aspect              | Partitioned          | Multilevel            | Coherent               | Replicated                |
|---------------------|----------------------|-----------------------|------------------------|---------------------------|
| Data location       | Sharded across nodes | L1 local + L2 shared  | Independent per node   | Full copy on every node   |
| Read performance    | Network hop required | L1 fast, L2 slower    | Fastest (pure local)   | Fastest (pure local)      |
| Write behavior      | Remote write to owner| Write through levels  | Local + invalidation   | Local + push to all peers |
| Consistency         | Strong (single owner)| Varies by config      | Eventual               | Eventual                  |
| Network overhead    | Medium               | Medium to high        | Low (invalidations)    | Medium (batched RPCs)     |
| Best for            | Large datasets       | Tiered access patterns| Read-heavy workloads   | Read-heavy, small datasets|

## Installation

Add `:nebulex_distributed` to your dependencies in `mix.exs`:

    def deps do
      [
        {:nebulex_distributed, "~> 3.0"},
        {:telemetry, "~> 0.4 or ~> 1.0"}, # For observability and monitoring
        {:decorator, "~> 1.4"},           # For declarative caching
      ]
    end

The `:telemetry` (observability and monitoring cache operations) and
`:decorator` (declarative caching) dependencies are optional but highly
recommended.

See each adapter's documentation for configuration and usage details.

---

*Consult [api-reference.md](api-reference.md) for complete listing*