Регистр

Локальное, децентрализованное и масштабируемое хранилище пар «ключ-значение» для процессов.

Позволяет разработчикам искать один или несколько процессов по заданному ключу. Если регистр поддерживает :unique ключи, ключ указывает на 0 или 1 процесс. Если регистр поддерживает :duplicate ключи, один ключ может указывать на любое количество процессов. В обоих случаях разные ключи могут идентифицировать один и тот же процесс.

Каждая запись в регистре ассоциирована с процессом, который зарегистрировал ключ. Если процесс завершается, ключи, связанные с этим процессом, автоматически удаляются. Все сравнения ключей в регистре выполняются с помощью операции совпадения (===/2).

Регистр может использоваться для различных целей, таких как поиск по именам (используя :via опцию), хранение свойств, пользовательские правила диспетчеризации или реализация pubsub. Ниже мы рассмотрим некоторые из этих вариантов использования.

Регистр также может быть прозрачно разбит на разделы, что обеспечивает более масштабируемое поведение при выполнении регистров в высококонкурентных средах с тысячами или миллионами записей.

Использование в `:via`

После запуска регистра с заданным именем с помощью Registry.start_link/1, можно использовать его для регистрации и доступа к именованным процессам, используя кортеж {:via, Registry, {registry, key}}:

{:ok, _} = Registry.start_link(keys: :unique, name: Registry.ViaTest)
name = {:via, Registry, {Registry.ViaTest, "agent"}}
{:ok, _} = Agent.start_link(fn -> 0 end, name: name)
Agent.get(name, & &1)
#=> 0
Agent.update(name, &(&1 + 1))
Agent.get(name, & &1)
#=> 1

В предыдущем примере нас не интересовало связывание значения с процессом:

Registry.lookup(Registry.ViaTest, "agent")
#=> [{self(), nil}]

Однако в некоторых случаях может потребоваться привязать значение к процессу, используя альтернативный кортеж {:via, Registry, {registry, key, value}}:

{:ok, _} = Registry.start_link(keys: :unique, name: Registry.ViaTest)
name = {:via, Registry, {Registry.ViaTest, "agent", :hello}}
{:ok, agent_pid} = Agent.start_link(fn -> 0 end, name: name)
Registry.lookup(Registry.ViaTest, "agent")
#=> [{agent_pid, :hello}]

До этого момента мы запускали Registry с помощью start_link/1. Однако обычно регистр запускается как часть дерева управления:

{Registry, keys: :unique, name: Registry.ViaTest}

Только регистры с уникальными ключами могут использоваться в :via. Если имя уже занято, функция, специфичная для данного случая, start_link (Agent.start_link/2 в примере выше), вернёт {:error, {:already_started, current_pid}}.

Использование в качестве диспетчера

Registry имеет механизм диспетчеризации, который позволяет разработчикам реализовывать пользовательскую логику диспетчеризации, срабатывающую от вызывающей стороны. Например, предположим, что у нас есть дублирующий регистр, запущенный следующим образом:

{:ok, _} = Registry.start_link(keys: :duplicate, name: Registry.DispatcherTest)

Вызывая register/3, разные процессы могут регистрироваться под заданным ключом и связывать любое значение под этим ключом. В этом случае давайте зарегистрируем текущий процесс под ключом "hello" и прикрепим к нему кортеж {IO, :inspect}:

{:ok, _} = Registry.register(Registry.DispatcherTest, "hello", {IO, :inspect})

Теперь сущность, заинтересованная в диспетчеризации событий для данного ключа, может вызвать dispatch/3, передав ключ и обратный вызов. Этот обратный вызов будет вызван со списком всех значений, зарегистрированных под запрашиваемым ключом, наряду с PID процесса, который зарегистрировал каждое значение, в форме кортежей {pid, value}. В нашем примере value будет кортежем {module, function} в приведенном коде:

Registry.dispatch(Registry.DispatcherTest, "hello", fn entries ->
  for {pid, {module, function}} <- entries, do: apply(module, function, [pid])
end)
# Prints #PID<...> where the PID is for the process that called register/3 above
#=> :ok

Диспетчеризация происходит в процессе, который вызывает dispatch/3, либо последовательно, либо параллельно в случае нескольких разделов (через запущенные задачи). Зарегистрированные процессы не участвуют в диспетчеризации, если их участие не происходит явно (например, путём отправки им сообщения в обратном вызове).

Кроме того, если при диспетчеризации произойдёт ошибка из-за неправильной регистрации, диспетчеризация всегда завершится неудачей, и зарегистрированный процесс не будет уведомлён. Поэтому давайте убедимся, что мы по крайней мере обрабатываем и сообщаем об этих ошибках:

require Logger

Registry.dispatch(Registry.DispatcherTest, "hello", fn entries ->
  for {pid, {module, function}} <- entries do
    try do
      apply(module, function, [pid])
    catch
      kind, reason ->
        formatted = Exception.format(kind, reason, __STACKTRACE__)
        Logger.error("Registry.dispatch/3 failed with #{formatted}")
    end
  end
end)
# Prints #PID<...>
#=> :ok

Вы также можете заменить всю систему apply явным отправлением сообщений. Это пример, который мы рассмотрим далее.

Использование как PubSub

Регистры также могут использоваться для реализации локальной, нераспределённой, масштабируемой PubSub, опираясь на функцию dispatch/3, аналогично предыдущему разделу: в этом случае, однако, мы будем отправлять сообщения каждому связанному процессу, вместо вызова определённой модульной функции.

В этом примере мы также установим количество разделов равным количеству активных планировщиков, что сделает регистр более производительным в высококонкурентных средах:

{:ok, _} =
  Registry.start_link(
    keys: :duplicate,
    name: Registry.PubSubTest,
    partitions: System.schedulers_online()
  )

{:ok, _} = Registry.register(Registry.PubSubTest, "hello", [])

Registry.dispatch(Registry.PubSubTest, "hello", fn entries ->
  for {pid, _} <- entries, do: send(pid, {:broadcast, "world"})
end)
#=> :ok

В приведённом примере сообщение {:broadcast, "world"} было разослано всем процессам, зарегистрированным под «темой» (или «ключом», как мы его называли до сих пор) "hello".

Третий аргумент, переданный в register/3, — это значение, связанное с текущим процессом. В предыдущем разделе мы использовали его при диспетчеризации, но в данном конкретном примере нас это не интересует, поэтому мы установили его в пустой список. При необходимости вы можете сохранить более значимое значение.

Регистрации

Поиск, диспетчеризация и регистрация эффективны и мгновенны, но отложены при отписке. Например, если процесс завершается, его ключи автоматически удаляются из регистра, но изменение может не распространиться немедленно. Это означает, что некоторые операции могут возвращать уже умершие процессы. В таких случаях это будет явно указано в документации функции.

Однако имейте в виду, что такие случаи обычно не вызывают проблем. В конце концов, процесс, на который ссылается PID, может завершиться в любой момент, включая период между получением значения из регистра и отправкой ему сообщения. Многие части стандартной библиотеки предназначены для решения этой проблемы, например, Process.monitor/1, которая будет доставлять сообщение :DOWN немедленно, если отслеживаемый процесс уже завершился, и send/2, которая действует как бездействие для завершённых процессов.

ETS

Обратите внимание, что регистр использует одну таблицу ETS плюс две таблицы ETS на каждый раздел.

Типы

body(): Шаблон, используемый для представления части формата вывода спецификации соответствия.
guard(): Фильтр для проверки при сопоставлении с объектами в реестре.
guards(): Список фильтров для проверки при сопоставлении с объектами в реестре.
key(): Тип ключей, разрешенных для регистрации.
keys(): Тип реестра.
listener_message(): Сообщение, которое реестр отправляет слушателям при регистрации или отмене регистрации процесса.
match_pattern(): Шаблон для сопоставления с объектами в реестре.
meta_key(): Тип ключей метаданных реестра.
meta_value(): Тип значений метаданных реестра.
registry(): Идентификатор реестра.
spec(): Полная спецификация соответствия, используемая при выборе объектов в реестре.
start_option(): Параметры, используемые для child_spec/1 и start_link/1
value(): Тип значений, разрешенных для регистрации.

Функции

child_spec(options): Возвращает спецификацию для запуска реестра под надзором.
count(registry): Возвращает количество зарегистрированных ключей в реестре. Операция выполняется за постоянное время.
count_match(registry, key, pattern, guards \\ []): Возвращает количество пар {pid, value} по заданному key в registry, которые соответствуют pattern.
count_select(registry, spec): Действует аналогично select/2, но возвращает только количество соответствующих записей.
delete_meta(registry, key): Удаляет метаданные реестра для заданного key в registry.
dispatch(registry, key, mfa_or_fun, opts \\ []): Вызывает обратный вызов со всеми записями под key в каждом разделе для заданного registry.
keys(registry, pid): Возвращает известные ключи для заданного pid в registry в произвольном порядке.
lookup(registry, key): Находит пару {pid, value} для заданного key в registry в произвольном порядке.
match(registry, key, pattern, guards \\ []): Возвращает пары {pid, value} по заданному key в registry, которые соответствуют pattern.
meta(registry, key): Считывает метаданные реестра, заданные в start_link/1.
put_meta(registry, key, value): Сохраняет метаданные реестра.
register(registry, key, value): Регистрирует текущий процесс под заданным key в registry.
select(registry, spec): Выбор ключей, идентификаторов процессов и значений, зарегистрированных с использованием полных спецификаций соответствия.
start_link(options): Запускает реестр как процесс-наблюдатель.
unregister(registry, key): Отменяет регистрацию всех записей для заданного key, связанных с текущим процессом в registry.
unregister_match(registry, key, pattern, guards \\ []): Отменяет регистрацию записей для ключей, соответствующих шаблону, связанных с текущим процессом в registry.
update_value(registry, key, callback): Обновляет значение для key для текущего процесса в уникальном registry.
values(registry, key, pid): Считывает значения для заданного key для pid в registry.

END_OF_DOCUMENT_MARKER

body()Source

@type body() :: [term()]

Шаблон, используемый для представления части формата вывода спецификации соответствия

guard()Source

@type guard() :: atom() | tuple()

Условие, подлежащее оценке при соответствии объектам в реестре

guards()Source

@type guards() :: [guard()]

Список условий, подлежащих оценке при соответствии объектам в реестре

key()Source

@type key() :: term()

Тип ключей, разрешенных при регистрации

keys()Source

@type keys() :: :unique | :duplicate

Тип реестра

listener_message()Source

@type listener_message() ::
  {:register, registry(), key(), registry_partition :: pid(), value()}
  | {:unregister, registry(), key(), registry_partition :: pid()}

Сообщение, которое реестр отправляет слушателям при регистрации или отмене регистрации процесса.

См. опцию :listeners в start_link/1.

match_pattern()Source

@type match_pattern() :: atom() | term()

Шаблон для соответствия объектам в реестре

meta_key()Source

@type meta_key() :: atom() | tuple()

Тип ключей метаданных реестра

meta_value()Source

@type meta_value() :: term()

Тип значений метаданных реестра

registry()Source

@type registry() :: atom()

Идентификатор реестра

spec()Source

@type spec() :: [{match_pattern(), guards(), body()}]

Полная спецификация соответствия, используемая при выборе объектов в реестре

start_option()Source

@type start_option() ::
  {:keys, keys()}
  | {:name, registry()}
  | {:partitions, pos_integer()}
  | {:listeners, [atom()]}
  | {:meta, [{meta_key(), meta_value()}]}

Параметры, используемые для child_spec/1 и start_link/1

value()Source

@type value() :: term()

Тип значений, разрешенных при регистрации

child_spec(options)Source

@spec child_spec([start_option()]) :: Supervisor.child_spec()

Возвращает спецификацию для запуска реестра под надзором.

См. Supervisor.

count(registry)Source

@spec count(registry()) :: non_neg_integer()

Возвращает количество зарегистрированных ключей в реестре. Выполняется за постоянное время.

Регистр

Типы

Функции

body()Source

guard()Source

guards()Source

key()Source

keys()Source

listener_message()Source

match_pattern()Source

meta_key()Source

meta_value()Source

registry()Source

spec()Source

start_option()Source

value()Source

child_spec(options)Source

count(registry)Source

count_match(registry, key, pattern, guards \\ [])Source

count_select(registry, spec)Source

delete_meta(registry, key)Source

dispatch(registry, key, mfa_or_fun, opts \\ [])Source

keys(registry, pid)Source

lookup(registry, key)Source

match(registry, key, pattern, guards \\ [])Source

meta(registry, key)Source

put_meta(registry, key, value)Source

register(registry, key, value)Source

select(registry, spec)Source

start_link(options)Source

unregister(registry, key)Source

unregister_match(registry, key, pattern, guards \\ [])Source

update_value(registry, key, callback)Source

values(registry, key, pid)Source