Erlang Basics

• Install On OSX brew install erlang.
• Launch REPL erl.
• Abort Ctrl+G then q or q().

All variables are immutable and named PascalCase. They are assigned for the first time using the pattern matching operator =.

> One = 1.
> Two = One + 1.

Atoms are constant literals, with a backing 4 or 8 byte integer. They are written in lowercase or with_understore. They are used in pattern matching.

Erlang has the usual boolean comparison operators and, or, xor, not. These operators always evaluate both sides of the equation, while andalso and orelse are shortcut operators.

Equality operators are freaky: =:= and =/=. They test for precise equality.

Comparison operators are slightly lighter: == and /=, they are more relaxed. For example:

> 1 =:= 1.0.
False
> 1 == 1.0.
True

The other comparison operators are just slightly weird: <, >, =< and >=.

Tuples group multiple items together: {point,10,5}. You can also destructure a tuple via pattern matching to an unbound variable:

> Point = {point,10,5}.
{point,10,5}
> {point,X,Y}=Point.
{point,10,5}
> X.
10

Tuples could be nested easily: {point,{10,5}}.

Lists in erlang are constructed like [E1,E2,...E3] and could have different elements inside: [1,2,{point,{3,4}},4.5].

There is a catch. Strings in erlang are also lists of numbers. If all numbers in a list could represent a letter, then erlang will print it as string.

To glue lists together use ++ and to split --:

> [1,2,3] ++ [4,5].
[1,2,3,4,5].
> [1,2,3] -- [1,2].
[3]

These operations are right-associative, meaning that they are done from right to left:

> [1,2,3]--[1,2]--[3].
[3]

You can use [Head|Tail] pattern to compose lists (adding head is fast in erlang) and also to descructure them, where | is called a cons. In fact, any list can be constructed with [E1|[E2|[E3]]].

Note, that we can construct an improper list [2|3], which will throw errors.

List comprehensions allow to generate and modify lists in a conscise way:

~[Expr || Gen1, Gen2...., Cond1, Cond2...]~.

For example:

> [{X,Y}||X<-[1,2],Y<-[1,2],X==Y].
[{1,2},{2,2}]

We can also use pattern matching and existing lists:

> Weather = [{ufa,sun},{moscow,rain},{odessa,fog},{spb,rain}].
[{ufa,sun},{moscow,rain},{odessa,fog},{spb,rain}]
> Rainy = [City || {City,rain} <-Weather].
[moscow, spb]

To express binary data we can use:

• hexadecimal notation: 16#AACCEE.
• bit syntax: <<16#AACCEE:24>> (put these bytes into 24 bit space).

For example:

% declare a bunch of bytes
> Bytes = <<13,234,12,34,41,1,151>>.
% Take first byte and treat the rest as binary
> <<First:8,Rest/binary>> = Bytes.

In general, binary segment could be described as:

• Value
• Value:Size
• Value/TypeSpecifier
• Value:Size/TypeSpecifier

Where Size is in bits, if TypeSpecifier is not provided. The latter could be a hyphen-separated list of:

• Type: integer (default), float, binary, bitstring, bits, utf8, utf16, utf32, bytes (synonym for binary), bits (synonym for bitstring).
• Sign: signed and unsigned (default), matters only for integer.
• Endianness: big (default), little and native (from the current CPU). This applies for integer, utf16, utf32 or float.
• Unit: this is written unit:integer, where the value must be between 1 and 256. It is used for field alignment.

Given that, it is trivial to parse TCP segment:

<<
  SourcePort:16,
  DestinationPort:16,
  AckNumber:32,
  DataOffset:4,
  _Reserved:4,
  Flags:8,
  WindowSize:16,
  CheckSum: 16,
  UrgentPointer:16,
  Payload/binary
>>
= SomeBinary.

Erlang has a common set of operators:

• bsr and bsl - bit shift left/right.
• band, bor, bxor, bnot

Binary strings are a bolted abstraction on top of lists: <<"Some string">>. It is hard to pattern-match them, so they are mainly used for text storage.

You can deal with binaries using a special form of comprehension syntax.

% Let us define some bytes
> Pixels = <<123,34,21,45,102,32,65,61,62>>.
<<123,34,21,45,102,32,65,61,62>>

% Read them as a sequence of RGBS
> RGBs = [ {R,G,B} || <<R:8,G:8,B:8>> <= Pixels ].
[{123,34,21},{45,102,32},{65,61,62}]

% convert these RGBs back to bits
> Bits = << <<R:8,G:8,B:8>> || {R,G,B} <- RGBs >>.
<<123,34,21,45,102,32,65,61,62>>

Erlang modules are represented as files with a bunch of attributes in -name(Attribute) form. The only required attribute is name: -module(useless), it should match to the file name without the extension.

-module(useless).
-export([add/2, multiply/2]).

add(A,B) ->
  A + B.

multiply(A,B) ->
  A * B.

In order to compile a module:

• in command line: erlc flags module.erl;
• in shell or a module: compile:file(module.erl);
• in shell: c(useless).;
• in Emacs buffer: C-c C-k (it will also load the module in REPL).

We call functions from the other modules as module:function(args). In order to importn the namespace:

-import(Module, [Function1/Arity, ..., FunctionN/Arity]).

Macros in Erlang are similar to compiler directives. They are defined as -define(MACRO,SomeValue). (where SomeValue is True if skipped), and could be referenced in the code as ?MACRO.

We also have some predefined macros:

• ?MODULE - current module as an atom
• ?FILE - current file name as a string
• ?LINE - current line as an integer

Macros can be tested: ifdef, else and endif. For example, you could provide a debugging macro:

-ifdef(DEBUGMODULE).
-define(DEBUG(S), io:format("dbg: "++S)).
-else.
-define(DEBUG(S), ok).
-endif.

?DEBUG("entering some function")

If DEBUGMODULE macro is defined, then we will have debugging, otherwise we will have an ok atom.

Compiler will capture all module metadata and make them available in module_info/0 function, for example useless:module_info().

Erlang provides pattern matching in the form of multiple function clauses separated by ;.

function(X) ->
  Expression;
function(Y) ->
  Expression;
function(_) ->
  Expression.

We can match on lists in the patterns:

head([Head|_]) -> Head;
head([])       -> [].

We can do even fancier stuff, by destructuring in function head:

add({Date = {YYYY,MM,DD}, Increment = {days, Days}}) ->
  {YYYY,MM,DD+Days}.

Guards are additional that can go in function head to make it more specific. The syntax is like this:

% constrain by Expr1 (must be true)
function(args) when Expr1 -> Expression.
% Expr1 and Expr2 must be true
function(args) when Expr1, Expr2 -> Expression.
% Expr1 or Expr2 must be true
function(args) when Expr1; Expr2 -> Expression.

You can also use andalso and orelse inside guards. They are similar, but can be nested, however shortcut operators can fail (normal guard can proceed even if the first argument fails with exception).

Guards will not accept user-defined functions! This is done to guarantee that we don't get any side effects there.

Guard patterns are defined with if inside functions, they share the syntax. They must have catch-all clause, though:

some(A) ->
  if A =:= 1 -> one;
  true -> something_else
  end.

Generally, if patterns were written to get benefit if case statement (below) but without the need to write full syntax.

Case allows to have normal pattern matching inside a function.

case Arg of:
  Pattern [Guards] -> Expression;
  Pattern [Guards] -> Expression;
  _ -> Expression
end.

In essence, this expression could be rewritten as

fun (Pattern) [Guards] -> Expression;
fun (Pattern) [Guards] -> Expression;
fun (_) -> Expression.

Just use whichever makes the code more simple. Performance differences are negligible.

Bound and unbound variables behave differently when we do pattern matching:

• unbound - attaches value to them;
• bound - error, unless new value is the same as the old one.

Type conversions in Erlang are implemented with BIFs in erlang module:

>  erlang:list_to_integer("54").
54
> erlang:integer_to_list(42).
"42"
> erlang:atom_to_list(atom).
"atom"

There are many more conversions of this type.

Type-test BIFs are special BIFs that can be used in guard clauses: is_binary, is_atom etc. They help to write declarative code:

Func(Arg) when is_atom(Arg) -> atom;
Func(Arg) when is_binary(Arg) -> binary;
...

It is usually advised to start writing a recursive function from a base case (a well known scenario, when recursion terminates).

Here is an example of function that calculates length of the list:

len([]) -> 0;
len([_]) -> 1;
len([_|Tail]) -> 1+len(Tail).

Tail recursion aims to eleminate stacking of recursive operations as they happen by reducing them as they happen. Erlang could optimize tail calls.

Let's rewrite our function to transform it into a tail recursion:

tail_len(N) -> tail_len(0,N).

tail_len(Acc,[]) -> Acc;
tail_len(Acc,[_]) -> Acc+1;
tail_len(Acc,[_,Tail]) -> tail_len(Acc+1,Tail).

If function is calling itself in a tail position (last expression to be evaluated is the function itelf), then Erlang VM could avoid storing current stack frame. This is called tail call optimization (a specific case of last call optimization).

Such optimizations make tail recursions useful and alvoid wasting a lot of memory. Even if tail call optimization doesn't work, large per-process stack of Erlang VM could help to handle some scenarios.

Just to get into the habit.

repeat/2 function:

repeat(0,_) -> [];
repeat(N,X) when N > 0 -> [X|repeat(N-1,X)].

and tail-recursive function:

tail_repeat(N,X) -> tail_repeat([], N, X).

tail_repeat(L, 0, _) -> L;
tail_repeat(L, N, X) when N > 0 -> tail_repeat([X | L], N-1, X).

Tail-recursive reverse function (note, that there is a BIF lists:reverse/1):

reverse(L) -> tail_reverse([],L).
tail_reverse(Acc, []) -> Acc;
tail_reverse(Acc, [H|T]) -> tail_reverse([H|Acc], T).

Tail-recursive sublist function:

head(L,N) -> reverse(head([], L, N)).

head(Acc, _, 0) -> Acc;
head(Acc, [], _) -> Acc;
head(Acc, [H|T], N) -> head([H|Acc], T, N-1).

Let's define a map/2 function:

map(_, []) -> [];
map(F, [H|T]) -> [F(H)|map(F,T)].

If we put it into a useless module and also add inc(X)->X+1, then:

> useless:map(fun useless:/1, [1,2,3]).
[2,3,4]

Always declaring functions can be boring, hence the inline version.

> Fn = fun(A) -> A end.
#Fun<erl_eval.6.90072148>
> Fn(1).
1

In general an anonymous function can be declared as:

fun(Arg1) -> Expr1, Expr2, ... Expr N;
(Args2) -> Expr1, Expr2, ... Expr N;
(Args3) -> Expr1, Expr2, ... Expr N
end

In erlang anonymous functions inherit the scope that they have been declared in. We can have closures (capturing some variables that were a part of the scope).

In the shell:

> Var = 1.
1.
> Closure = fun() -> Var end.
#Fun....
> Closure().
1

Assigning function to a variable

Fx = fun useless:is_odd/2

Just a bunch of common helpers:

• lists:reverse/1;
• lists:map/2 (Select in LINQ);
• lists:filter/2 (Where in LINQ);
• lists:foldl/3 (Aggregate, starting left);
• lists:foldr/3;
• all/2 and any/2;
• dropwhile/2 and takewhile/2;
• partition/2 - generates two lists, where predicate matches and not;
• flatten/1 - select many.

Errors can be created by erlang:error(Reason). They will abort execution of the function and return a stack trace with all the arguments.

These are called with exit/1. They don't have a stack trace and are generally used to pass "last breath" information between the processes.

Throws (created by throw/1) are used to control the excecution flow. They can also be used for non-local returns in deep recursion (e.g. deep function would throw exception for a top-level function to catch and return a default value to the user).

Exceptions can be handled with try...of...catch block:

try Expression of
  SuccessPattern -> Expression;
  SuccessPattern -> Expression
catch
  TypeOfError:ExceptionPattern -> Expression;
  TypeOfError:ExceptionPattern -> Expression
end.

where TypeOfError can be: error, throw or exit, defaulting to throw if skipped.

There also is a special catch-all pattern: _:_, which will handle any exception type.

Expression between try...of could be a function or just a whole bunch of expressions: Expr1, Expr2... ExprN. This section is called protected.

It is also possible to have finally block, which can't retrun any value but would be used for its side effects (e.g. closing a file). It is called after in erlang.

The protected section can't be tail-recursive, since the VM would keep a reference, in case an exception shows up. Code between catch..of isn't protected and could be tail-recursive, unless after block is specified.

This is a weird one. Keyword catch could be used alone to capture all either exception or a good result out of an expression: catch Expression.

Records are a hack that were added to the language later. They provide a syntactic sugar on top of the ordinary typles.

For storing small amounts of data we have a property list (proplist) and an ordered dictionary (orddict).

A process in erlang is just a function that can be scheduled to run via spawn/1. This function returns pid in form of <0.160.0> which can be used to communicate with the process.

The process terminates when the function returns.

BIF self/0 returns the pid of the current process.

You send messages with ! (bang) operator, which works in form of Pid ! hello and returns a message (so that it can be passed to multiple processes).

You can dump all messages via flush/0 which would simply print them. For real work use receive expression, which looks similar to case pattern matching:

receive
    Pattern1 when Guard ->
        Expr1;
    Pattern2 when Guard ->
        Expr2;
    Pattern3 ->
        Expr3;
    _ -> Expr4
end.

Let's write us a small module:

-module(spell).
-compile(export_all).

cast() ->
    receive
        {heal, Amount} ->
            io:format("Healing ~p~n",[Amount]);
        {damage, Amount} ->
            io:format("Ouch for ~p~n", [Amount]);
        _ ->
            io:format("WTF?~n")
    end.

This function could be launched either via spawn(fun spell:cast/0) or via a helper spawn(spell, cast, []), which takes a module, function and arguments.

Once launched, cast would sit around waiting for the receive to get a message. It will process it and terminate.

> S1 = spawn(spell, cast, []).
<0.181.0>
> S1 ! {boom}.
WTF?
{boom}

The only way to know if the recipient is alive and got message is by sending a reply. We can do that by packaging return address into a tuple.

cast2() ->
    receive
        {From, heal, Amount} ->
            io:format("Healing ~p~n",[Amount]),
            From ! "healing!";
        {From,damage, Amount} ->
            io:format("Ouch for ~p~n", [Amount]),
            From ! "damage";
        _ ->
            io:format("WTF?~n")
    end.

Then run in a shell:

> spawn(spell,cast2,[]) ! {self(), heal,2}.
Healing 2
{<0.155.0>,heal,2}
> flush().
Shell got "healing!"
ok

Now we just need to make sure that the process can process more than one message. We can do that by making it tail-recursive:

summon(Life) ->
    receive
        {From,damage, Amount} when Amount >= Life ->
            % no recursion here
            io:format("Dead! ~p~n", [Amount]),
            From ! {self(), "dead"};

        {From,damage, Amount} ->
            io:format("Ouch! ~p~n", [Amount]),
            From ! {self(), "this hurts!"},
            summon(Life - Amount);
        {From, heal, Amount} ->
            io:format("Healing ~p~n",[Amount]),
            From ! {self(), "healing!"},
            summon(Life + Amount);
        _ ->
            io:format("WTF?~n"),
            summon(Life)
    end.

The process will continue running till we damage it too much. Note that we also pass the state through that recursion.

Message structure is a bit like internal implementation detail. Do we really need to expose it that much? Let's encapsulate the details.

summon_wolf() ->
    spawn(?MODULE, summon, [3]).

fireball(Pid) ->
    Pid ! { self(), damage, 2},
    receive
        {_, Message} ->
            Message
    end.

ointment(Pid) ->
    Pid ! { self(), heal, 1},
    receive
       {_, Message} ->
            Message
    end.

This hides all the dirty details and allows us to focus damage dealing:

0> Wolf = spell:summon_wolf().
<0.289.0>
> spell:fireball(Wolf).
Ouch! 2
"this hurts!"
> spell:fireball(Wolf).
Dead! 2
"dead"

There is a problem. If we send spell:fireball/1 to a non-existent process (or the dead one) from our shell, then it will freeze. We are stuck in a receive deadlock.

To work around the issue, receive has an after Timeout construct:

fireball2(Pid) ->
    Pid ! { self(), damage, 2},
    receive
        {_, Message} ->
            Message
    after 1000 -> timeout
    end.

ointment2(Pid) ->
    Pid ! { self(), heal, 1},
    receive
        {_, Message} ->
            Message
    after 1000 -> timeout
    end.

After also can accept infinity atom (in case timeout is passed as an argument and we want to wait forever).

There are two special cases - sleeping (receive without any patterns) and trying to get messages without waiting (receive with zero timeout).

We can perform a selective receive by ignoring some messages (which puts them into a save queue for later processing). This is done via:

important() ->
    receive
        {Priority, Message} when Priority > 10 ->
            [Message | important()]
    after 0 ->
            normal()
    end.

normal() ->
    receive {_, Message} ->
            [Message, normal()]
    after 0 ->
        []
    end.

The approach has a pitfall: selective receive puts non-matching messages into a special save queue, which is then traversed on each message.

We can work around that by:

• provide a catch-all Unexpected variable which will log and discard;
• store messages in min-heap, gb_trees module or whichever structure is applicable.

When a process terminates, it always terminates with an exit reason, which can be of any term. If exit reason is atom normal then the process terminated normally.

A process can terminate:

• when a run-time error occurs with {Reason,Stack};
• terminate by itself by calling exit(Reason), error(Reason, [Args]), fault(Reason, [Args]);
• when exit signal is received with a reason other than normal.

Terminating processes emit exit signals to all linked processes. These kill a process, unless the reason is normal.

A process can call exit(Pid, Reason) to emit an exit signal with Reason to the target process. Sender is unaffected.

You can link/1 current process to another by PID, making them emit exit signals to each other on termination. Linking is idempotent.

Note, that in link(spawn(Function)) spawned process could finish before link is established. It is better to use atomic spawn_link/1.

A process can be configured to trap incoming exit signals and convert them into messages of {'Exit', FromPid, Reason} that are put into mailbox.

One exception - if a reason is kill (e.g. from exit(Pid, kill)), then this will bypass the trap and kill the process. Upon termination, an exit signal with killed is sent to all linked processed (to avoid killing them unconditionally).

Monitors are a unidirectional way to monitor if the process is alive and when it goes down. A process can setup a monitor via monitor(process, Pid) which would return Ref reference to the monitor. That reference could be used to demonitor/1 the process.

When a monitored process dies, we get a message:

{'DOWN', Ref, process, Pid, Reason}

If the process didn't exist in the first place we would get the message immediately with Reason set to noproc.

To give a process a name, use erlang:register(Name,Pid). If the process dies, it will loose its name. Or you can use unregister/1 to do it manually. Then, use whereis(Name) to get Pid (or an undefined).