Packages

partisan

5.0.0-beta.15
5.0.3 5.0.2 5.0.1 5.0.0 5.0.0-rc.16 5.0.0-rc.8 5.0.0-rc.2 5.0.0-rc.1 5.0.0-beta.24 5.0.0-beta.21 5.0.0-beta.20 5.0.0-beta.18 5.0.0-beta.17 5.0.0-beta.16 5.0.0-beta.15 5.0.0-beta.14 5.0.0-beta.13 4.1.0 3.0.0 2.1.0 2.0.0 1.4.1 1.4.0 1.3.4 1.3.3 1.3.2 1.3.1 1.3.0 1.2.0 1.1.0 1.0.2 1.0.1 1.0.0 0.3.0 0.2.3 0.2.2 0.2.1 0.2.0 0.1.1 0.1.0 0.0.1

Partisan is a scalable and flexible, TCP-based membership system and distribution layer for the BEAM.

HexDocs

Current section

41 Versions

Jump to
Readme
41 Versions
3 Dependencies
4 Dependants
Files
Activity
Show whitespace

Compare versions

46 files changed
+7578 additions
-2907 deletions
  @@ -1,5 +1,50 @@
1 1 # CHANGELOG
2 2
3 + # v5.0.0-beta.15
4 +
5 + ### Bug Fixes
6 + * General bug fixes including:
7 + * #121 updated_members should only accept a list of maps (an never a list of nodes)
8 + * fix wrong calls to `self()` and `node()` as opposed to their partisan counterparts
9 + * Fixed bugs in `partisan_monitor`
10 + * Several bug fixes in the OTP implementation
11 + * Several bug fixes in the CT suite
12 +
13 + ### Changes
14 + * Changed signature of partisan_membership_strategy and the implementing modules; added API e.g. `join(state(), partisan:node_spec(), state())` is now ` join(partisan:node_spec(), state(), state())` which is more natural.
15 + * Added partisan_membership_strategy API functions, so that pluggable manager can call these functions
16 + * Some other naming changes to disambiguate e.g. membership -> members
17 + * moved some opt types from partisan_monitor to partisan module
18 + * Fixed mising of gen_ and partisan_gen function calls.
19 + * Made `channel` options to be respected across the stack
20 + * Added channel configuration to `partisan_monitor` calls.
21 + * Added channel to OTP behaviours.
22 + * The messages and the monitor signals will be sent using the configured channel.
23 + * overloaded gen_server/statem functions to accept options including channel so that we do not add another function to the API
24 + * store the Partisan opts in the process dict (again to avoid modifying our changed versions of the behaviours)
25 + *
26 + * Configuration parameters renaming. Several configuration parameters were renamed. Check `partisan_config` module description. The old parameters are still accepted but are renamed during startup.
27 + * Deprecated the `partisan_peer_service_manager:myself` callback
28 + * Fix `partisan_util` term encoding and renamed function; added compression option for encoding and for memberhip payload
29 +
30 +
31 +
32 + ### Additions
33 + * Added the following modules:
34 + * `partisan_supervisor` behaviour
35 + * Added the following functions:
36 + * `partisan:exit/2`
37 + * `partisan:send/2`
38 + * `partisan:send/3`
39 + * `partisan:send_after/3`
40 + * `partisan:send_after/4`
41 + * `partisan:cancel_timer/1`
42 + * `partisan:cancel_timer/2`
43 + * Peer Service manager now allows subscribing to events per channel
44 + * `partisan_peer_service_manager:on_up/3` accepting a channel
45 + * `partisan_peer_service_manager:on_down/3` accepting a channel
46 +
47 +
3 48 # v5.0.0-beta.14
4 49
5 50 ## API
  @@ -201,7 +246,7 @@ In general, the API was redesigned to concentrate all functions around two modul
201 246 * `lager` dependency has been removed and all logging is done using the new Erlang `logger`
202 247 * Most uses of the `orddict` module have been replaced by maps for extra performance and better usability
203 248 * Most API options using `proplists` module have been replaced by maps for extra performance and better usability
204 - * In several functions the computation of options (merging user provided with defaults, validation, etc.) has been posponed until (and only if) it is needed for extra performance e.g. `partisan_pluggable_peer_servie_manager:forward_message`
249 + * In several functions the computation of options (merging user provided with defaults, validation, etc.) has been postponed until (and only if) it is needed for extra performance e.g. `partisan_pluggable_peer_servie_manager:forward_message`
205 250 * More utils in `partisan_util`
206 251 * Added `ex_doc` (Elixir documentation) rebar plugin
207 252 * Upgraded the following dependencies:
  @@ -1,17 +1,31 @@
1 1 # Partisan
2 2
3 - [![Build Status](https://travis-ci.org/lasp-lang/partisan.svg?branch=master)](https://travis-ci.org/lasp-lang/partisan)
3 + ![Version](https://img.shields.io/badge/version-5.0.0--beta.15-blue?style=for-the-badge)
4 + ![Build Status](https://img.shields.io/github/actions/workflow/status/lasp-lang/partisan/build_and_test.yml?&branch=master&label=build-status&style=for-the-badge)
4 5
5 6 Partisan is a scalable and flexible, TCP-based membership system and distribution layer for the BEAM. It bypasses the use of Distributed Erlang for manual connection management via TCP, and has several pluggable backends for different deployment scenarios.
6 7
8 + Partisan is a runtime system that enables greater scalability and reduced latency for distributed actor applications.
9 +
10 + * Partisan improves scalability by allowing the application developer to specialize the overlay network to the application’s communication patterns.
11 + * Partisan achieves lower latency by leveraging several predominately automatic optimizations that result in the efficient scheduling of messages.
12 + * Bring Your Own Overlay - Partisan exposes an API for users to implement their own overlays; application developers must simply implement the `membership_strategy` interface for handling messages. Partisan automatically uses this membership strategy for processing incoming and outgoing messages to the system – the application developer only needs to handle internal state transitions and supplying the system with an updated list of members. Partisan automatically sets up required connections, serializes and deserializes messages, performs failure detection, and message forwarding. This makes it possible to implement protocols with very little code; our implementation of the full-mesh membership protocol is 152 LOC.
13 + * Partisan is the first distributed actor system to expose this level of control to the application developer, improving the performance of existing actor application and enabling new types of actor applications.
14 +
15 + ## Getting started
16 + See the documentation for Partisan at [hex.pm](https://hexdocs.pm/partisan/partisan.html).
17 +
18 + Alternatively you can build the documentation yourself locally using `make docs`.
19 + The resulting documentation will be found in the `docs` directory, just open the `index.html` file with your preferred web browser.
20 +
7 21
8 22 ## Why do we need Partisan?
9 23
10 24 Erlang/OTP, specifically distributed erlang (a.k.a. `disterl`), uses a full-mesh overlay network. This means that in the worst case scenario all nodes are connected-to and communicate-with all other nodes in the system.
11 25
12 - **Failure detector**. These nodes send periodic heartbeat messages to their connected nodes and deem a node "failed" or "unreachable" when it misses a certain number of heartbeat messages i.e. `net_tick_time` setting in `disterl`.
26 + **Failure detector**. These nodes send periodic heartbeat messages to their connected nodes and deem a node "failed" or "unreachable" when it misses a certain number of heartbeat messages i.e. the `net_tick_time` setting in `disterl`.
13 27
14 - Due to this hearbeating and other issues in the way Erlang handles certain internal data structures, Erlang systems present a limit to the number of connected nodes that depending on the application goes between 60 and 200 nodes.
28 + Due to this heartbeating and other issues in the way Erlang handles certain internal data structures, Erlang systems present a limit to the number of connected nodes that depending on the application goes between 60 and 200 nodes.
15 29
16 30 Also, Erlang conflates control plane messages with application messages on the same TCP/IP connection and uses a single TCP/IP connection between two nodes, making it liable to the [Head-of-line blocking](https://en.wikipedia.org/wiki/Head-of-line_blocking) issue. This also leads to congestion and contention that further affects latency.
17 31
  @@ -32,7 +46,7 @@ Partisan was also designed to handle failures:
32 46 Partisan was designed to increase scalability, reduce latency and improve failure detection for Erlang/BEAM distributed applications.
33 47
34 48 * Scalability
35 - * Provides serveral overlays that are configurable at runtime
49 + * Provides several overlays that are configurable at runtime
36 50 * `partisan_pluggable_peer_service_manager`: full mesh with TCP-based failure detection. All nodes maintain active connections to all other nodes in the system using one or more TPC connections.
37 51 * `partisan_hyparview_peer_service_manager.`: modified implementation of the HyParView protocol, peer-to-peer, designed for high scale, high churn environments. A hybrid partial view membership protocol, with TCP-based failure detection.
38 52 * `partisan_client_server_peer_service_manager.`: star topology, where clients communicate with servers, and servers communicate with other servers.
  @@ -54,25 +68,39 @@ Partisan was designed to increase scalability, reduce latency and improve failur
54 68 * Monitoring: Partisan offers an API similar to the modules `erlang` and `net_kernel` for monitoring nodes and remote processes. Notice this currently only works for `partisan_pluggable_peer_service_manager` backend.
55 69 * Other
56 70 * On join, gossip is performed immediately, instead of having to wait for the next gossip round.
57 - * Single node testing, facilitated by a disterl control channel for figuring out which ports the peer service is operating at.
71 + * Single node testing, facilitated by a `disterl` control channel for figuring out which ports the peer service is operating at.
58 72
59 73
60 74 ## Requirements
61 75
62 76 * Erlang/OTP 24+
63 77
64 -
65 - ## Documentation
66 - Find the documentation for Partisan releases at [hex.pm](https://hex.pm).
67 -
68 - Alternatively you can build it yourself locally using `make docs`.
69 - The resulting documentation will be found in the `docs` directory, just open the `index.html` file with your preferred Web Browser.
70 -
71 -
72 78 ## Who is using Partisan
73 79
80 + ### Projects
81 +
82 + * [Bondy](https://github.com/bondy-io/bondy)
74 83 * [Erleans](https://github.com/erleans/erleans)
75 84 * [PlumDB](https://github.com/Leapsight/plum_db)
76 - * [Bondy](https://github.com/bondy-io/bondy)
85 +
86 + ### Organizations
87 +
77 88 * [Leapsight](https://www.leapsight.com)
78 89
90 +
91 + ## Reference
92 +
93 + ### Academic Papers
94 +
95 + * [Partisan: Enabling Real-World Protocol Evaluation](https://dl.acm.org/doi/10.1145/3231104.3231106) - ApPLIED '18: Proceedings of the 2018 Workshop on Advanced Tools, Programming Languages, and PLatforms for Implementing and Evaluating Algorithms for Distributed systems, Christopher Meiklejohn
96 + * [Partisan: Enabling Cloud-Scale Erlang Applications](https://arxiv.org/abs/1802.02652), Christopher Meiklejohn, Heather Miller
97 + * [Partisan: Scaling the Distributed Actor Runtime](https://www.usenix.org/system/files/atc19-meiklejohn.pdf) - 2019 USENIX Annual Technical Conference, Christopher S. Meiklejohn and Heather Miller, Carnegie Mellon University; Peter Alvaro, UC Santa Cruz
98 + * [HyParView: a membership protocol for reliable gossip-based broadcast](https://asc.di.fct.unl.pt/~jleitao/pdf/dsn07-leitao.pdf), Joao Leitao, Jose Pereira Luis Rodrigues.
99 + * [X-BOT: A Protocol for Resilient Optimization of Unstructured Overlay Networks](https://www.academia.edu/2901632/X_BOT_A_Protocol_for_Resilient_Optimization_of_Unstructured_Overlay_Networks), Joao Leitao, Jose Pereira Luis Rodrigues.
100 +
101 + ### Presentations
102 +
103 + * [Rethinking the Language Runtime for Scale](http://www.erlang-factory.com/euc2016/christopher-meiklejohn) - Erlang User Conference 2016, Christopher S. Meiklejohn
104 + * [Partisan: Scaling the Distributed Actor Runtime](https://www.usenix.org/conference/atc19/presentation/meiklejohn) - 2019 USENIX Annual Technical Conference, Christopher S. Meiklejohn
105 + * [Partisan: testable, high performance, large scale distributed Erlang](https://codesync.global/media/partisan-testable-high-performance-large-scale-distributed-erlang/) - Code BEAM SF 2019, Christopher S. Meiklejohn
106 + * [Distributed Erlang: From Datacenter Applications to Planetary Scale Applications](https://www.youtube.com/watch?v=01vedKGBQkQ), Christopher Meiklejohn.
  @@ -18,7 +18,7 @@
18 18 <<"src/partisan_config.erl">>,
19 19 <<"src/partisan_full_membership_strategy.erl">>,<<"src/partisan_gen.erl">>,
20 20 <<"src/partisan_gen_fsm.erl">>,<<"src/partisan_gen_server.erl">>,
21 - <<"src/partisan_gen_statem.erl">>,
21 + <<"src/partisan_gen_statem.erl">>,<<"src/partisan_gen_supervisor.erl">>,
22 22 <<"src/partisan_hyparview_peer_service_manager.erl">>,
23 23 <<"src/partisan_hyparview_xbot_peer_service_manager.erl">>,
24 24 <<"src/partisan_inet.erl">>,
  @@ -65,4 +65,4 @@
65 65 [{<<"app">>,<<"uuid">>},
66 66 {<<"optional">>,false},
67 67 {<<"requirement">>,<<"~>2.0.2">>}]}]}.
68 - {<<"version">>,<<"5.0.0-beta.14">>}.
68 + {<<"version">>,<<"5.0.0-beta.15">>}.
  @@ -1,15 +1,37 @@
1 1 -define(APP, partisan).
2 2 -define(PEER_IP, {127, 0, 0, 1}).
3 3 -define(PEER_PORT, 9090).
4 + -define(DEFAULT_TIMEOUT, 5000). % Same as OTP
5 + %% Idea from erpc.erl
6 + -define(MAX_INT_TIMEOUT, 4294967295).
7 + -define(TIMEOUT_TYPE, 0..?MAX_INT_TIMEOUT | 'infinity').
8 + -define(IS_VALID_TMO_INT(TI_), (is_integer(TI_)
9 + andalso (0 =< TI_)
10 + andalso (TI_ =< ?MAX_INT_TIMEOUT))).
11 + -define(IS_VALID_TMO(T_), ((T_ == infinity) orelse ?IS_VALID_TMO_INT(T_))).
12 + -define(IS_VALID_TIME(T), (is_integer(T) andalso T >= 0)).
13 + -define(IS_VALID_MFA(M, F, A),
14 + (is_atom(M) andalso is_atom(F) andalso is_list(A))
15 + ).
4 16
5 17
6 -
18 + %% =============================================================================
7 19 %% PLUMTREE
20 + %% =============================================================================
21 +
22 +
23 +
8 24 -define(PLUMTREE_OUTSTANDING, partisan_plumtree_broadcast).
9 25 -define(BROADCAST_MODS, [partisan_plumtree_backend]).
10 26
11 27
28 +
29 + %% =============================================================================
12 30 %% CHANNELS
31 + %% =============================================================================
32 +
33 +
34 +
13 35 -define(DEFAULT_CHANNEL, undefined).
14 36 -define(MEMBERSHIP_CHANNEL, partisan_membership).
15 37 -define(RPC_CHANNEL, rpc).
  @@ -33,10 +55,7 @@
33 55 -define(PERIODIC_INTERVAL, 10000).
34 56
35 57 -define(PEER_SERVICE_MANAGER,
36 - partisan_config:get(
37 - partisan_peer_service_manager,
38 - ?DEFAULT_PEER_SERVICE_MANAGER
39 - )
58 + (partisan_config:get(peer_service_manager, ?DEFAULT_PEER_SERVICE_MANAGER))
40 59 ).
41 60
42 61 -define(MEMBERSHIP_STRATEGY,
  @@ -75,8 +94,54 @@
75 94
76 95
77 96
97 +
78 98 %% =============================================================================
79 - %% PROTOCOLS
99 + %% PROTOCOLS: HYPARVIEW
100 + %% =============================================================================
101 +
102 + -define(XBOT_MIN_INTERVAL, 5000).
103 + -define(XBOT_RANGE_INTERVAL, 60000).
104 + % parameter used for xbot optimization
105 + % - latency (uses ping to check better nodes)
106 + % - true (always returns true when checking better)
107 + -define(HYPARVIEW_XBOT_ORACLE, latency).
108 + -define(HYPARVIEW_XBOT_INTERVAL,
109 + rand:uniform(?XBOT_RANGE_INTERVAL) + ?XBOT_MIN_INTERVAL
110 + ).
111 +
112 + -define(HYPARVIEW_DEFAULTS, #{
113 + active_max_size => 6,
114 + active_min_size => 3,
115 + active_rwl => 6,
116 + passive_max_size => 30,
117 + passive_rwl => 6,
118 + random_promotion => true,
119 + random_promotion_interval => 5000,
120 + shuffle_interval => 10000,
121 + shuffle_k_active => 3,
122 + shuffle_k_passive => 4,
123 + xbot_enabled => false,
124 + xbot_interval => ?HYPARVIEW_XBOT_INTERVAL
125 + }).
126 +
127 +
128 + -type config() :: #{
129 + active_max_size := non_neg_integer(),
130 + active_min_size := non_neg_integer(),
131 + active_rwl := non_neg_integer(),
132 + passive_max_size := non_neg_integer(),
133 + passive_rwl := non_neg_integer(),
134 + random_promotion := boolean(),
135 + random_promotion_interval := non_neg_integer(),
136 + shuffle_interval := non_neg_integer(),
137 + shuffle_k_active := non_neg_integer(),
138 + shuffle_k_passive := non_neg_integer(),
139 + xbot_enabled := boolean(),
140 + xbot_interval := non_neg_integer()
141 + }.
142 +
143 + %% =============================================================================
144 + %% PROTOCOLS: SCAMP
80 145 %% =============================================================================
81 146
82 147 %% Scamp protocol.
  @@ -115,8 +180,6 @@
115 180 -define(DEFAULT_LAZY_TICK_PERIOD, 1000).
116 181 -define(DEFAULT_EXCHANGE_TICK_PERIOD, 10000).
117 182
118 - -define(XBOT_MIN_INTERVAL, 5000).
119 - -define(XBOT_RANGE_INTERVAL, 60000).
120 183
121 184 -if(?OTP_RELEASE >= 25).
122 185 -define(PARALLEL_SIGNAL_OPTIMISATION(L),
  @@ -128,7 +191,3 @@
128 191 -define(PARALLEL_SIGNAL_OPTIMISATION(L), L).
129 192 -endif.
130 193
131 - % parameter used for xbot optimization
132 - % - latency (uses ping to check better nodes)
133 - % - true (always returns true when checking better)
134 - -define(XPARAM, latency).
  @@ -39,16 +39,22 @@
39 39 rebar3_hex
40 40 ]}.
41 41
42 - {shell, [{apps, [partisan]}]}.
42 + {shell, [
43 + {apps, [partisan]},
44 + {config, "config/sys.config"}
45 + ]}.
43 46
44 47 {profiles, [
45 48 {test, [
46 49 {extra_src_dirs, ["protocols"]},
47 50
48 - {deps, [{eredis, {git, "https://github.com/wooga/eredis.git", {tag, "master"}}},
51 + {deps, [
52 + {eredis,
53 + {git, "https://github.com/wooga/eredis.git", {tag, "master"}}},
49 54 {jsx, "3.1.0"},
50 55 {proper, "1.4.0"},
51 - recon]},
56 + recon
57 + ]},
52 58
53 59 {relx, [{release, {partisan, "5.0.0-beta.11"}, [eredis, partisan]},
54 60 {extended_start_script, true},
  @@ -85,15 +91,9 @@
85 91 <<"CHANGELOG.md">>,
86 92 <<"CODE_OF_CONDUCT.md">>
87 93 ]},
88 - {main, <<"partisan">>},
94 + {main, <<"README.md">>},
89 95 {extra_section, "Pages"},
90 - {api_reference, false},
91 - %% Paths from root dir
92 - {extras, [
93 - <<"README.md">>,
94 - <<"LICENSE">>,
95 - <<"CHANGELOG.md">>
96 - ]},
96 + {api_reference, true},
97 97 {groups_for_extras, #{
98 98 <<"Introduction">> => [
99 99 ],
  @@ -105,7 +105,8 @@
105 105 {groups_for_modules, [
106 106 {<<"API">>, [
107 107 partisan,
108 - partisan_config
108 + partisan_config,
109 + partisan_peer_service
109 110 ]},
110 111 {<<"Peer Service">>, [
111 112 partisan_peer_service,
  @@ -150,6 +151,7 @@
150 151 partisan_gen,
151 152 partisan_gen_server,
152 153 partisan_gen_statem,
154 + partisan_gen_supervisor,
153 155 partisan_rpc,
154 156 partisan_rpc_backend,
155 157 partisan_monitor,
Loading more files…