Partisan replaces Distributed Erlang's full mesh with a swappable overlay

The problem is the full mesh and the single connection

The diagnosis is specific. Distributed Erlang uses a full-mesh overlay network, so in the worst case every node is connected to and communicates with every other node. Failure detection works by sending periodic heartbeats and deeming a node failed when it misses a certain number of them, the `net_tick_time` setting. Because of that heartbeating and other issues with how Erlang handles certain internal data structures, Erlang systems present a limit on the number of connected nodes that, depending on the application, goes between 60 and 200. The second problem is transport: Erlang conflates control plane messages with application messages on the same TCP connection and uses a single connection between two nodes, making it liable to head-of-line blocking, which also leads to congestion and contention that further affects latency.

Four overlays, and you pick at runtime

Partisan ships several overlays that are configurable at runtime, and the choice maps onto a deployment topology. `partisan_pluggable_peer_service_manager` is a full mesh with TCP-based failure detection, where all nodes maintain active connections to all other nodes using one or more TCP connections. `partisan_hyparview_peer_service_manager` is a modified implementation of the HyParView protocol, peer-to-peer and designed for high scale, high churn environments, as a hybrid partial view membership protocol with TCP-based failure detection. `partisan_client_server_peer_service_manager` is a star topology where clients talk to servers and servers talk to other servers. `partisan_static_peer_service_manager` is static membership, where connections are explicitly made between nodes. The overlays are specialised to particular application communication patterns and the system does not alter application behaviour.

Bring your own overlay, in a surprisingly small amount of code

The most interesting claim in the README is the bring-your-own-overlay API. Partisan exposes an API for users to implement their own overlays, and the developer only has to implement the `membership_strategy` interface for handling messages. Partisan then uses that strategy for processing incoming and outgoing messages, while the developer handles internal state transitions and supplies an updated list of members. Everything else is automatic: Partisan sets up required connections, serializes and deserializes messages, performs failure detection, and does message forwarding. The stated payoff is that protocols become implementable with very little code, and the example given is the full-mesh membership protocol at 152 lines of code. Partisan is described as the first distributed actor system to expose this level of control to the application developer.

The latency work is about channels and message dropping

Two mechanisms carry the latency improvements. The first is parallelism, by configuring the number of TCP connections between nodes, which the README calls named channels. The second is pushing background and maintenance traffic onto other communication channels, so that the head-of-line blocking caused by background activity is avoided. The third mechanism is monotonicity, which enables load shedding. Monotonic channels drop messages when state is increasing on the channel, to reduce load and the transmission of redundant information, and the README names the intended use cases: growing monotonic hash rings, objects designated with vector clocks, and CRDTs. That is a real trade-off rather than a free win, since a dropped message is only harmless when the state on the channel is monotonic.

The OTP behaviours are regenerated at build time

The installation story has a wrinkle that is worth understanding before you start. Partisan generates Partisan-flavoured copies of the OTP behaviour modules at compile time, and the tutorial explains how that is wired up. For an Erlang project the dependency goes into rebar.config:

%% rebar.config
{deps, [{partisan, "6.3.0"}]}.

For an Elixir project it goes into mix.exs as a normal dependency. Then `rebar3 compile`, or `mix deps.get && mix compile`, and on every compile Partisan automatically generates the copies of `gen_server`, `gen_statem`, `supervisor` and the rest into its own `ebin/`, with no extra configuration required on the consumer side. The generation uses a build-time OTP modules generator named `partisan_gen_server`, `partisan_gen_statem` and so on. The consequence to be aware of is that your build now produces a second set of behaviour modules, and the tutorial covers when you would care about that.

Failure handling is a list of things that go wrong

The design goals section lists the failure modes Partisan was built to handle: message omission, message reordering, which can happen in Erlang during reconnections, state loss, bit flips, message corruption, faulty failure detectors, and others. Failure detection itself is performed over TCP, connections are verified at each gossip round, and the system offers reliable delivery and stronger ordering along with fault injection for testing. One behaviour change is easy to miss and useful to know: on join, gossip is performed immediately instead of the application having to wait. The monitoring API offers something similar to the `erlang` and `net_kernel` modules for watching nodes and remote processes, and the README notes that this currently only works with the `partisan_pluggable_peer_service_manager` backend, which is a real caveat if you were planning to combine monitoring with a HyParView overlay.

Testing runs at two levels, and the version line is uneven

The build tooling shows the scale of the test effort. The Makefile has a `ci-light` and a `ci-heavy` pair of targets, and the repository has separate workflows for build and test and for a heavy test suite, with the badge names `build-and-test` and `heavy-test-suite`. There are dedicated targets for acceptor, core and monitor tests, a security test, property-based tests driven by PropEr with system models and implementation modules selectable from the command line, and a reference to exhaustive model checking in the demers, lampson and skeen targets. The version numbers are worth noting: the README badge says 6.3.0, the last push to the develop branch was on 2026-10-15, but the tagged releases are v5.0.2 from 2025-08-10, v4.2.0 from 2023-01-30 and v3.0.0 from 2018, so the tagged cadence is slow and the working branch is where the activity is.

Editorial conclusion

Adopt Partisan when you run a BEAM cluster large enough that Distributed Erlang's full mesh hurts, or when your nodes are spread across geographies where a single TCP connection per pair causes head-of-line blocking. Do not adopt it for a small cluster on one datacentre, because the overhead it adds buys you nothing there and the release cadence is slow, with v5.0.2 in 2025 and v4.2.0 in 2023. Verify first which overlay backend fits your failure model, that the monitoring API works with the backend you pick since it currently only works with the pluggable one, and that you can live with the build-time generator that rewrites your OTP behaviour modules.

Frequently asked questions

Official sources

1. lasp-lang/partisan on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases