Structs Our Friends

Introduction

Just to get everyone up to speed; Structs are a great because they provide compile time checks. Compile-time checks are awesome as we can catch errors before we run our application in the run-time. Structs also allow us to make custom data types, and we can implement protocols that amongst other things allow us to tell Elixir how it should enumerate over our data type, or insert items into our data type using Protocols.

They are by no means perfect. The compiler can only check the keys of a struct. To test the actual values we need special tools, such as dialyzer; but any kind of compile time checks are good in my book.

As you might know a struct is part of a module, they really are simple maps with a special field called __struct__. This can be seen by using the build in function is_map/1 on a struct and using functions from the Map module; let’s test this out using the %URI{} struct from Elixir standard lib.

iex> uri = %URI{}
%URI{
  authority: nil,
  fragment: nil,
  host: nil,
  path: nil,
  port: nil,
  query: nil,
  scheme: nil,
  userinfo: nil
}
iex> is_map(uri)
true
iex> Map.keys(uri)
[:__struct__, :authority, :fragment, :host, :path, :port, :query, :scheme, :userinfo]

Defining structs

We can define our own structs using the defstruct/1 macro in a module.

defmodule Person do
  defstruct [:id, :name, age: 0]
end

As we can see we can define fields, and we can define default values. In our Person example we would get a person with age zero if we don’t specify a value when we use it to create a new person; nil is the default value if none is specified.

iex> %Person{name: "Martin"}
%Person{age: 0, id: nil, name: "Martin"}

Benefits of using structs for internal process state

My favorite use of structs is to define the state of a process. This has a couple of benefits that I would like to address. Take the following example:

defmodule Counter1 do
  use GenServer

  defstruct [:access_time, value: 0]

  # Client API
  def start_link(opts \\ []) do
    GenServer.start_link(__MODULE__, opts)
  end

  def inc(pid, n) when is_integer(n), do: GenServer.call(pid, {:inc, n})

  def count(pid), do: GenServer.call(pid, :count)

  # Server callbacks
  def init(_opts) do
    {:ok, %__MODULE__{}}
  end

  def handle_call({:inc, n}, _from, state) when n > 0 do
    %{value: new_value} =
      new_state = %__MODULE__{
        value: state.value + n,
        access_time: DateTime.utc_now()
      }

    {:reply, new_value, new_state}
  end

  def handle_call(:count, _from, state) do
    {:reply, state.value, %__MODULE__{access_time: DateTime.utc_now()}}
  end
end

This implement a GenServer that store a counter. We can increment it and we can ask it for its current count. Every time we access the counter we will update the last time it was accessed with the current time.

iex> {:ok, pid} = Counter1.start_link
{:ok, #PID<0.142.0>}
iex> Counter1.count(pid)
0
iex> Counter1.inc(pid, 5)
5

But we have a bug in our counter. Instead of reading on, try and see if you can spot it!

iex> {:ok, pid} = Counter1.start_link
{:ok, #PID<0.145.0>}
iex> Counter1.inc(pid, 5)
5
iex> Counter1.count(pid)
5
iex> Counter1.count(pid)
0
# If we ask for the count we will get the current count, but it will
# then be set to zero. Look at the Counter1 implementation again and
# see if you can spot why.

We overwrite the state every time we access it—and we get the default values. That bug is a nasty one, because it is subtle, and as such it is not wrong behavior so it manifest itself the next time we access the data—not where the error is happening.

We can protect ourselves from these kinds of bugs by using the @enforce_keys module attribute. I have had great success setting a value that normally wouldn’t get set and enforce that key. Then we can allow the compiler to help us. Observe the following example where I define an id field and enforce it; The first time I initialize the struct I will set it, and then the compiler will complain if I overwrite instead of updating the state!

defmodule Counter2 do
  use GenServer

  @enforce_keys :id
  defstruct [:id, :access_time, value: 0]

  # Client API
  def start_link(opts \\ []) do
    GenServer.start_link(__MODULE__, opts)
  end

  def inc(pid, n) when is_integer(n), do: GenServer.call(pid, {:inc, n})

  def count(pid), do: GenServer.call(pid, :count)

  # Server callbacks
  def init(_opts) do
    <<id::integer-size(64)>> = :crypto.strong_rand_bytes(8)
    {:ok, %__MODULE__{id: id}}
  end

  def handle_call({:inc, n}, _from, state) when n > 0 do
    %{value: new_value} =
      new_state = %__MODULE__{
        state
        | value: state.value + n,
          access_time: DateTime.utc_now()
      }

    {:reply, new_value, new_state}
  end

  def handle_call(:count, _from, state) do
    {:reply, state.value, %__MODULE__{state | access_time: DateTime.utc_now()}}
  end
end

Updating state

Another great thing for using structs as state is the struct!/1 function. This can be used to initialize a struct with a set of values coming from an enumerable that produces values of two-tuples (key/value). I like to use this function in the init/1 callback like so:

defmodule Person do
  use GenServer

  @enforce_keys [:id, :name]
  defstruct [:id, :name, age: 0]

  # Client API
  def start_link(opts) do
    GenServer.start_link(__MODULE__, opts)
  end

  def info(pid), do: GenServer.call(pid, :info)

  def update(pid, info) when is_list(info), do: GenServer.cast(pid, {:update, info})

  # Server callbacks
  def init(opts) do
    opts = Keyword.put_new_lazy(opts, :id, &generate_id/0)
    {:ok, struct!(__MODULE__, opts)}
  end

  defp generate_id(), do: Enum.random(1..0xFFFF)

  def handle_cast({:update, update}, state) do
    {:noreply, struct!(state, update)}
  end

  def handle_call(:info, _from, state) do
    {:reply, state, state}
  end
end

This will allow us to pass in a keyword list setting any value defined in our struct. The run-time will complain if we set something that does not exist, and we can easily provide default values that are computed using the functions from the Keyword-module. In our example we provide a computed default value for :id if it is not set; being able to set a specific id is helpful in testing.

iex> {:ok, pid} = Person.start_link([name: "Agner Krarup Erlang"])
{:ok, #PID<0.227.0>}
iex> Person.info(pid)
%Person{age: 0, id: 20375, name: "Agner Krarup Erlang"}
iex> Person.update(pid, [age: 52])
:ok
iex> Person.info(pid)
%Person{age: 52, id: 20375, name: "Agner Krarup Erlang"}

This way of updating internal state is certainly not for every use-case. Sometimes we would like to shield our state management a bit more.

Conclusion

Using structs for internal state management has many benefits; we can let the compiler help us because we are more precise in our intent—preventing us from overwriting our state when we don’t want to—and we can use struct/1 and struct!/1 in combination with Keyword lists to set and update the values.

While the state should be private to the process and not leak to the outside, I still think it is beneficial to be able to peak into the state structure like this. It is hugely beneficial in testing, as we can make assertions on the state-struct and get notified on where we break our tests when the implementation change, and we can even help us when we inspect our process state using functions like :sys.get_state/1.

That was what I wanted to show today.