Справочная информация и функции для работы с протоколами.

Протокол определяет API, который должен быть определён его реализациями. Протокол определяется с помощью Kernel.defprotocol/2, а его реализации с помощью Kernel.defimpl/3.

Пример

В Elixir есть два способа проверить количество элементов в структуре данных: length и size. length означает, что информация должна быть вычислена. Например, length(list) нужно пройти по всему списку, чтобы вычислить его длину. С другой стороны, tuple_size(tuple) и byte_size(binary) не зависят от размера кортежа и бинарного представления, так как информация о размере предварительно вычислена в структуре данных.

Хотя Elixir включает в себя специализированные функции, такие как tuple_size, binary_size и map_size, иногда нам нужно получить размер структуры данных независимо от её типа. В Elixir мы можем писать полиморфный код, то есть код, который работает с различными формами/типами, используя протоколы. Протокол размера можно реализовать следующим образом:

defprotocol Size do
  @doc "Calculates the size (and not the length!) of a data structure"
  def size(data)
end

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

defimpl Size, for: BitString do
  def size(binary), do: byte_size(binary)
end

defimpl Size, for: Map do
  def size(map), do: map_size(map)
end

defimpl Size, for: Tuple do
  def size(tuple), do: tuple_size(tuple)
end

Наконец, мы можем использовать протокол Size для вызова соответствующей реализации:

Size.size({1, 2})
# => 2
Size.size(%{key: :value})
# => 1

Обратите внимание, что мы не реализовали его для списков, так как у списков нет size информации, а её значение необходимо вычислить с помощью length.

Структура данных, для которой вы реализуете протокол, должна быть первым аргументом всех функций, определённых в протоколе.

Можно реализовать протоколы для всех типов Elixir:

• Структуры (см. раздел "Протоколы и структуры" ниже)
• Tuple
• Atom
• List
• BitString
• Integer
• Float
• Function
• PID
• Map
• Port
• Reference
• Any (см. раздел "Возврат к Any" ниже)

Протоколы и структуры

Настоящее преимущество протоколов проявляется при их использовании совместно со структурами. Например, Elixir поставляется с множеством типов данных, реализованных как структуры, например, MapSet. Мы можем реализовать протокол Size для этих типов тоже:

defimpl Size, for: MapSet do
  def size(map_set), do: MapSet.size(map_set)
end

При реализации протокола для структуры, опция :for может быть опущена, если вызов defimpl/3 находится внутри модуля, который определяет структуру:

defmodule User do
  defstruct [:email, :name]

  defimpl Size do
    # two fields
    def size(%User{}), do: 2
  end
end

Если реализация протокола не найдена для данного типа, вызов протокола приведёт к исключению, если не настроено обращение к Any. Также доступны удобства для создания реализаций на основе уже существующих. Обратитесь к defstruct/1 для получения дополнительной информации о выводе протоколов.

Возврат к Any

В некоторых случаях может быть удобно предоставить реализацию по умолчанию для всех типов. Это можно сделать, установив атрибут @fallback_to_any в true в определении протокола:

defprotocol Size do
  @fallback_to_any true
  def size(data)
end

Протокол Size теперь может быть реализован для Any:

defimpl Size, for: Any do
  def size(_), do: 0
end

Хотя приведенная выше реализация, вероятно, не является разумной. Например, не имеет смысла говорить, что PID или целое число имеют размер 0. Это одна из причин, почему @fallback_to_any — это поведенческий параметр с выбором.

Для большинства протоколов правильным поведением является выброс ошибки, когда протокол не реализован.

Несколько реализаций

Протоколы также могут быть реализованы для нескольких типов одновременно:

defprotocol Reversible do
  def reverse(term)
end

defimpl Reversible, for: [Map, List] do
  def reverse(term), do: Enum.reverse(term)
end

Внутри defimpl/3 можно использовать @protocol для доступа к реализуемому протоколу и @for для доступа к модулю, для которого он определяется.

Типы

Определение протокола автоматически определяет тип с нулевой арностью, названный t, который можно использовать следующим образом:

@spec print_size(Size.t()) :: :ok
def print_size(data) do
  result =
    case Size.size(data) do
      0 -> "data has no items"
      1 -> "data has one item"
      n -> "data has #{n} items"
    end

  IO.puts(result)
end

@spec выше показывает, что все типы, разрешённые для реализации данного протокола, являются допустимыми типами аргументов для данной функции.

Настройка

Доступны следующие атрибуты модуля для настройки протокола:

• @fallback_to_any - при значении true, разрешает переадресацию протокола к любому

• @undefined_impl_description - строка с дополнительным описанием, которое будет использоваться в Protocol.UndefinedError, когда поиск реализации завершается неудачно. Эта опция применяется только если @fallback_to_any не установлена в true

Консолидация

Для ускорения обработки протоколов, когда все реализации протокола известны заранее, обычно после компиляции всего кода Elixir в проекте, Elixir предоставляет возможность консолидации протоколов. Консолидация напрямую связывает протоколы с их реализациями таким образом, что вызов функции из консолидированного протокола эквивалентен вызову двух удалённых функций — одной для идентификации правильной реализации и другой для вызова реализации.

Консолидация протоколов по умолчанию применяется ко всем проектам Mix во время компиляции. Это может стать проблемой во время тестирования. Например, если вы хотите реализовать протокол во время тестирования, реализация не будет иметь эффекта, так как протокол уже был консолидирован. Одним из возможных решений является включение каталогов компиляции, специфичных для вашей тестовой среды, в ваш mix.exs:

def project do
  ...
  elixirc_paths: elixirc_paths(Mix.env())
  ...
end

defp elixirc_paths(:test), do: ["lib", "test/support"]
defp elixirc_paths(_), do: ["lib"]

Затем вы можете определить реализации, специфичные для тестовой среды, внутри test/support/some_file.ex.

Другой подход — отключить консолидацию протоколов во время тестирования в вашем mix.exs:

def project do
  ...
  consolidate_protocols: Mix.env() != :test
  ...
end

Если вы используете Mix.install/2, вы можете сделать это, передав опцию consolidate_protocols:

Mix.install(
  deps,
  consolidate_protocols: false
)

Хотя это не рекомендуется, так как это может повлиять на производительность вашего кода.

И наконец, обратите внимание, что все протоколы компилируются с debug_info установленным в true, независимо от установленного значения в компиляторе elixirc Информация отладки используется для консолидации и удаляется после консолидации, если не установлено глобальное значение.