This module handles the validation, access and modification of Partisan configuration options. Some options will only take effect after a restart of the Partisan application, while other will take effect while the application is still running.

As per Erlang convention the options are given using the sys.config file under the partisan application section.

Example

  [
      ...
      {partisan, [
          {listen_addrs, [
              #{ip => {127, 0, 0, 1}, port => 12345}
          ]},
          {channels, #{
              data => #{parallelism => 4}
          }},
          {remote_ref_format, improper_list},
          {tls, true},
          {tls_server_options, [
              {certfile, "config/_ssl/server/keycert.pem"},
              {cacertfile, "config/_ssl/server/cacerts.pem"},
              {keyfile, "config/_ssl/server/key.pem"},
              {verify, verify_none}
          ]},
          {tls_client_options, [
              {certfile, "config/_ssl/client/keycert.pem"},
              {cacertfile, "config/_ssl/client/cacerts.pem"},
              {keyfile, "config/_ssl/client/key.pem"},
              {verify, verify_none}
          ]}
      ]}
  ]

Options

The following is the list of all the options you can read using get/1 and get/2, and modify using the sys.config file and set/2.

See Deprecated Options below.

binary_padding

A boolean value indicating whether to pad encoded messages whose external binary representation consumes less than 65 bytes.

broadcast

TBD

broadcast_mods

TBD

causal_labels

TBD

channels

Defines the channels to be used by Partisan. The option takes either a channels map where keys are channel names (partisan:channel()) and values are channel options (partisan:channel_opts()), or a list of values where each value can be any of the following types:

• a channel name (partisan:channel()) e.g. the atom foo
• a channel with options: {channel(), channel_opts()}
• a monotonic channel using the tuple {monotonic, Name :: channel()} e.g. {monotonic, bar}. This is a legacy representation, the same can be achieved with {bar, #{monotonic => true}}

The list can habe a mix of types and during startup they are all coerced to channels map. Coercion works by defaulting the channel's parallelism to the value of the global option parallelism (which itself defaults to 1), and the channel's monotonic to false.

Finally the list is transformed to a map where keys are channel names and values are channel map representation.

Example

Given the following option value:

  [
      foo,
      {monotonic, bar},
      {bar, #{parallelism => 4}}
  ]

The coerced representation will be the following map (which is a valid input and the final representation of this option after Partisan starts).

  #{
      foo => #{monotonic => false, parallelism => 1},
      bar => #{monotonic => true, parallelism => 1},
      baz => #{monotonic => false, parallelism => 4},
  }

connect_disterl

A configuration that is intended solely for testing of the partisan_full_membership_strategy (See membership_strategy). It defines whether to use Distributed Erlang (disterl) in addition to Partisan channels. Defaults to false.

Notice that this setting does not prevent you having both disterl and Partisan enabled for your release. However, you need to have special care to avoid mixing the two, for example by calling a partisan_gen_server that uses Partisan for distribution with gen_server that uses disterl.

connection_interval

Interval of time between peer connection attempts

connection_jitter

TBD

disable_fast_forward

TBD

disable_fast_receive

TBD

distance_enabled

TBD

egress_delay

TBD

exchange_selection

TBD

exchange_tick_period

TBD

gossip

If true gossip is used to disseminate membership to peers. Default is true. At the moment used only by partisan_full_membership_strategy.

hyparview

The configuration for the partisan_hyparview_peer_service_manager. A list with the following properties:

• active_max_size - Defaults to 6.
• active_min_size - Defaults to 3.
• active_rwl - Active View Random Walk Length. Defaults to 6.
• passive_max_size - Defaults to 30.
• passive_rwl - Passive View Random Walk Length. Defaults to 6.
• random_promotion - A boolean indicating if random promotion is enabled. Defaults true.
• random_promotion_interval - Time after which the protocol attempts to promote a node in the passive view to the active view. Defaults to 5000.
• shuffle_interval - Defaults to 10000.
• shuffle_k_active - Number of peers to include in the shuffle exchange. Defaults to 3.
• shuffle_k_passive - Number of peers to include in the shuffle exchange. Defaults to 4.

ingress_delay

TBD

lazy_tick_period

TBD

listen_addrs

A list of listen_addr() objects. This overrides peer_ip and peer_port and its the preferred way to configure the peer listener. If missing, the peer_ip property will be used, unless is also missing, in which case the nodename's host part will be used to determine the IP address.

The listen_addr() object can be represented using lists, binaries, tuples or maps as shown in the following example:

  {listen_addrs, [
     "127.0.0.1:12345",
     <<"127.0.0.1:12345">>,
     {"127.0.0.1", "12345"},
     {{127, 0, 0, 1}, 12345},
     #{ip => "127.0.0.1", port => "12345"},
     #{ip => <<"127.0.0.1">>, port => <<"12345">>},
     #{ip => {127, 0, 0, 1}, port => 12345}
  ]}

Notice the above example will result in the following, as equivalent terms are deduplicated.

  {listen_addrs, [
     #{ip => {127, 0, 0, 1}, port => 12345}
  ]}

membership_binary_compression

A boolean value or an integer in the range from 0..9 to be used with erlang:term_to_binary/2 when encoding the membership set for broadcast.

A value of true is equivalent to integer 6 (equivalent to option compressed in erlang:term_to_binary/2). A value of false is equivalent to 0 (no compression).

Default istrue.

membership_strategy

The membership strategy to be used with partisan_pluggable_peer_service_manager. Default is partisan_full_membership_strategy

membership_strategy_tracing

TBD

name

TBD

orchestration_strategy

TBD

parallelism

TBD

peer_service_manager

The peer service manager to be used. An implementation of the partisan_peer_service_manager behaviour which defines the overlay network topology and the membership view maintenance strategy. Default is partisan_pluggable_peer_service_manager.

peer_ip

The IP to use for the peer connection listener. If undefined, the IP address will be resolved using the nodename's host (the part to the right of the @ character. If the IP address cannot be resolved, it will default to {127,0,0,1}.

peer_port

The port numner for the peer connection listener.

periodic_enabled

TBD

periodic_interval

TBD

pid_encoding

TBD

random_seed

TBD

ref_encoding

TBD

register_pid_for_encoding

TBD

remote_ref_format

Defines how partisan remote references pids, references and registered names will be encoded. See partisan_remote_ref).

Accepts the following atom values:

• uri - remote references will be encoded as binary URIs.
• tuple - remote references will be encoded as tuples (the format used by Partisan v1 to v4).
• improper_list - remote references will be encoded as improper lists, similar to how aliases are encoded by the OTP modules.

This option exists to allow the user to tradeoff between memory and latency. In terms of memory uri is the cheapest, followed by improper_list. In terms of latency tuple is the fastest followed by improper_list. The default is improper_list a if offers a good balance between memory and latency.

  1> partisan_config:set(remote_ref_format, uri).
  ok
  2> partisan:self().
  <<"partisan:pid:nonode@nohost:0.1062.0">>
  3> partisan_config:set(remote_ref_format, tuple).
  4> partisan:self().
  {partisan_remote_reference,
     nonode@nohost,
     {partisan_process_reference,"<0.1062.0>"}}
  5> partisan_config:set(remote_ref_format, improper_list).
  6> partisan:self().
  [nonode@nohost|<<"Pid#<0.1062.0>">>]

remote_ref_uri_padding

If true and the URI encoding of a remote reference results in a binary smaller than 65 bytes, the URI will be padded. The default is false.

  1> partisan_config:set(remote_ref_binary_padding, false).
  1> partisan:self().
  <<"partisan:pid:nonode@nohost:0.1062.0">>
  2> partisan_config:set(remote_ref_binary_padding, true).
  ok
  3> partisan:self().
  <<"partisan:pid:nonode@nohost:0.1062.0:"...>>

replaying

TBD

reservations

TBD

retransmit_interval

When option retransmission is set to true in the partisan:forward_opts() used in a call to partisan:forward_message/3 and message delivery fails, the Peer Service will enqueue the message for retransmission. This option is used to control the interval of time between retransmission attempts.

shrinking

TBD

tag

The role of this node when using the Client-Server topology implemented by {link partisan_client_server_peer_manager}.

Options

• undefined - The node acts as a normal peer in all other topologies. This the default value
• client - The node acts as a client. To be used only in combination with {partisan_peer_manager, partisan_client_server_peer_manager}
• server - The node acts as a server. To be used only in combination with {partisan_peer_manager, partisan_client_server_peer_manager}

tls

A boolean value indicating whether channel connections should use TLS. If enabled, you have to provide a value for tls_client_options and tls_server_options. The default is false.

tls_client_options

The TLS socket options used when establishing outgoing connections to peers. The configuration applies to all Partisan channels. The default is [].

Example

  {tls_client_options, [
      {certfile, "config/_ssl/client/keycert.pem"},
      {cacertfile, "config/_ssl/client/cacerts.pem"},
      {keyfile, "config/_ssl/client/key.pem"},
      {verify, verify_none}
  ]}

tls_server_options

The TLS socket options used when establishing incoming connections from peers. The configuration applies to all Partisan channels. The default is [].

Example

  {tls_server_options, [
      {certfile, "config/_ssl/server/keycert.pem"},
      {cacertfile, "config/_ssl/server/cacerts.pem"},
      {keyfile, "config/_ssl/server/key.pem"},
      {verify, verify_none}
  ]}

tracing

a boolean value. The default is false.

xbot_interval

TBD

Deprecated Options

The following is the list of options have been deprecated. Some of them have been renamed and/or moved down a level in the configuration tree.

arwl

HyParView's Active View Random Walk Length. Defaults to 6. Use active_rwl in the hyparview option instead.

fanout

The number of nodes that are contacted at each gossip interval.

max_active_size

HyParView's Active View Random Walk Length. Defaults to 6. Use active_max_size in the hyparview option instead.

max_passive_size

HyParView's Active View Random Walk Length. Defaults to 30. Use passive_max_size in the hyparview option instead.

mix_active_size

HyParView's Active View Random Walk Length. Defaults to 3. Use active_min_size in the hyparview option instead.

passive_view_shuffle_period

Use shuffle_interval in the hyparview option instead.

peer_port

Use listen_addrs instead.

partisan_peer_service_manager

Use peer_service_manager instead.

prwl

HyParView's Passive View Random Walk Length. Defaults to 6. Use passive_rwl in the hyparview option instead.

random_promotion

Use random_promotion in the hyparview option instead.

random_promotion_period

Use random_promotion_interval in the hyparview option instead.

remote_ref_as_uri

Use {remote_ref_format, uri} instead