Fix errors with ref/4 IEx helper

[fertapric]

In addition, I've included the documentation for that function.

Before:

$ iex
Erlang/OTP 21 [erts-10.0.4] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe] [dtrace]

Interactive Elixir (1.7.0) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> make_ref
#Reference<0.2597424430.1465122823.223385>
iex(2)> ref("0.2597424430.1465122823.1")
#Reference<0.2597424430.1465122823.1>
iex(3)> ref(0, 2597424430, 1465122823, 1)
** (ArgumentError) argument error
    :erlang.list_to_ref('<0.2597424430..1465122823..1.>')
    (iex) lib/iex/helpers.ex:1220: IEx.Helpers.ref/4
iex(3)>

After:

$ bin/iex
Erlang/OTP 21 [erts-10.0.4] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe] [dtrace]

Interactive Elixir (1.8.0-dev) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> ref("0.2597424430.1465122823.1")
#Reference<0.2597424430.1465122823.1>
iex(2)> ref(0, 2597424430, 1465122823, 1)
#Reference<0.2597424430.1465122823.1>
iex(3)>

These functions were included in this commit

[josevalim]

@fertapric we don't have doctests enabled for this module, so we need to add some unit tests too.

[josevalim]

@fertapric ping!

[fertapric]

I just wanted to mention that I did not forget about this one :)

I was doing some tests using the new ref/1 and I got curious due to some unexpected? results:

iex(1)> make_ref()
#Reference<0.3013689594.4010541059.29671>
iex(2)> :erlang.list_to_ref('#Ref<0.3013689594.4010541059.29671>')
#Reference<0.3013689594.4010541059.29671>
iex(3)> :erlang.list_to_ref('#Ref<3.3013689594.4010541059.29671>')
#Reference<0.3013689594.4010541059.29671>
iex(4)> :erlang.list_to_ref('#Ref<0.301.401054.29671>')
** (ArgumentError) argument error
    :erlang.list_to_ref('#Ref<0.301.401054.29671>')

(4) shows that not all possible number combinations are valid to create a Reference. I guessed references were not just random numbers, and the numbers had to follow some set of rules. Everything good here.

However, I was not expecting (3) to return a modified reference. I would expect an ArgumentError, but not a different set of numbers.

I looked a bit in the Erlang/OTP codebase, and I'm currently checking these parts of the codebase:

• https://github.com/erlang/otp/blob/master/erts/emulator/beam/erl_bif_unique.c#L45-L58
• https://github.com/erlang/otp/blob/master/erts/emulator/beam/erl_term.h#L658-L981

According to that, Ref only contains 3 numbers, so I'm not sure if the first one should always be 0.

I also suspect that ref[0] is not related to the first number #Reference<num1.num2.num3.num4>, and num1 is more related to the marker, but I haven't looked that internal code that much yet.

I was inspecting the code to check if it would be an error that should be reported upstream. But I don't have that much time to investigate :(

I thought maybe you know a little more about it and you could give me some more details or tips? cc @michalmuskala

[fertapric]

Either way, I'll finish this PR today. Bug or not, Elixir is not responsible of it :)

[josevalim]

@fertapric I believe the first part is the node reference. 0 is local node.

[michalmuskala]

Yeah, I believe it is. I would expect it to fail, similar to what happens for external PIDs or ports

[fertapric]

@josevalim Tests added.

Btw, I found out that :erlang.list_to_pid('<3.21.32>') also behaves the same:

iex(1)> :erlang.list_to_pid('<0.21.32>')
#PID<0.21.32>
iex(2)> :erlang.list_to_pid('<3.21.32>')
#PID<0.21.32>

However, if I do the same experiments in a cluster of nodes:

iex(n2@127.0.0.1)37> :erlang.list_to_pid('<3.21.32>')
** (ArgumentError) argument error
    :erlang.list_to_pid('<3.21.32>')
iex(n2@127.0.0.1)37> :erlang.list_to_pid('<0.21.32>')
#PID<0.21.32>
iex(n2@127.0.0.1)38> :erlang.list_to_ref('#Ref<3.1.2.3>')
** (ArgumentError) argument error
    :erlang.list_to_ref('#Ref<3.1.2.3>')
iex(n2@127.0.0.1)38> :erlang.list_to_ref('#Ref<0.1.2.3>')
#Reference<0.1.2.3>

🤷‍♂️

[michalmuskala]

Thank you! ❤️