Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Distribution and Ports

Ports, NIFs and TCP sockets

Talk to the outside world from Erlang: open_port for external programs, NIFs and port drivers, gen_tcp servers and clients, active and passive sockets.

Erlang processes live inside the virtual machine, but useful programs must also talk to files, other programs and the network. This lesson covers the three ways in: ports for external programs, NIFs for native code and sockets for networking with gen_tcp. Each fits the actor model: the outside world appears as a process that sends and receives messages.

Ports: running an external program

A port is a special process-like object connected to an operating system process or device. The owner process sends it data with ! or port_command/2 and receives replies as messages.

ERLANG
Port = open_port({spawn, "sort"}, [use_stdio, exit_status, binary]),
port_command(Port, <<"pear\napple\nfig\n">>).

Better to avoid the shell and give the executable and arguments explicitly:

ERLANG
Port = open_port({spawn_executable, "/bin/echo"},
                 [{args, ["hello", "world"]}, exit_status, binary, stderr_to_stdout]),
receive
    {Port, {data, Data}} -> io:format("got: ~s", [Data])
end,
receive
    {Port, {exit_status, Status}} -> io:format("exit status ~p~n", [Status])
end.

The messages from a port always have the form {Port, {data, Bytes}}, {Port, {exit_status, N}} or {'EXIT', Port, Reason} if the owner traps exits. Useful options:

Option Meaning
binary Data arrives as binaries instead of lists
{line, MaxLen} Deliver one line at a time as {eol, Line} or {noeol, Part}
{packet, N} Length-prefixed messages (1, 2 or 4 byte header)
exit_status Send {Port, {exit_status, N}} when the program ends
{cd, Dir}, {env, ...} Working directory and environment

If the Erlang process owning the port dies, the port is closed, and well-behaved external programs notice end of input on stdin and exit. If the external program crashes, the VM is not affected: only a message arrives. That isolation is the main reason to prefer ports over native code. The price is a slower round trip through the operating system's pipes.

NIFs and drivers

A NIF (Native Implemented Function) is a C, C++ or Rust function loaded into the VM and called like any other Erlang function. It is fast but dangerous: a crash or an endless loop in a NIF takes down the whole VM, and a long-running NIF blocks a scheduler. Rules: keep NIFs short (under about a millisecond), or use dirty schedulers (ERL_NIF_DIRTY_JOB_CPU_BOUND) for longer work, and test extremely carefully.

ERLANG
-module(fastmath).
-export([add/2]).
-nifs([add/2]).
-on_load(init/0).

init() -> erlang:load_nif("./fastmath", 0).
add(_A, _B) -> erlang:nif_error(nif_library_not_loaded).

The Erlang version is a stub replaced when the shared library loads. Port drivers are the older linked-in alternative; use NIFs, or safer options such as ports, the erl_interface C library, or a separate node written in another language that speaks the distribution protocol.

TCP sockets with gen_tcp

gen_tcp is part of the standard library. A server listens, accepts connections and hands each to a process.

ERLANG
-module(echo).
-export([start/1]).

start(Port) ->
    {ok, Listen} = gen_tcp:listen(Port, [binary, {packet, line},
                                         {active, false}, {reuseaddr, true}]),
    spawn(fun() -> accept(Listen) end).

accept(Listen) ->
    {ok, Socket} = gen_tcp:accept(Listen),
    Pid = spawn(fun() -> serve(Socket) end),
    ok = gen_tcp:controlling_process(Socket, Pid),
    accept(Listen).

serve(Socket) ->
    case gen_tcp:recv(Socket, 0) of
        {ok, Line} ->
            gen_tcp:send(Socket, Line),
            serve(Socket);
        {error, closed} ->
            ok
    end.

A client:

ERLANG
{ok, S} = gen_tcp:connect("localhost", 7777, [binary, {packet, line}, {active, false}]),
gen_tcp:send(S, <<"hello\n">>),
{ok, <<"hello\n">>} = gen_tcp:recv(S, 0, 2000),
gen_tcp:close(S).

One process per connection is the Erlang way: a crashing handler affects only that client, and thousands of idle connections cost almost nothing.

Active and passive mode

  • {active, false} (passive): you call gen_tcp:recv/2,3 yourself. Simple, but blocks.
  • {active, true}: incoming data is sent as {tcp, Socket, Data} messages, plus {tcp_closed, Socket} and {tcp_error, Socket, Reason}. Convenient with receive, but a fast sender can flood the mailbox.
  • {active, once} or {active, N}: deliver one message (or N), then go passive until you re-enable it. This gives flow control and is the recommended style for servers.
ERLANG
serve(Socket) ->
    inet:setopts(Socket, [{active, once}]),
    receive
        {tcp, Socket, Data} -> gen_tcp:send(Socket, Data), serve(Socket);
        {tcp_closed, Socket} -> ok;
        {tcp_error, Socket, _Reason} -> ok
    end.

{packet, N} and {packet, line} frame the stream so that you get whole messages rather than arbitrary chunks, since TCP is a byte stream. Use ssl for TLS, gen_udp for UDP, and for HTTP use a library such as cowboy, inets (httpd) or httpc.

Ways to reach outside the VM

Port External program via pipes, safe
NIF Native function, fast, can crash the VM
gen_tcp Sockets, one process per connection
Another node Speak distribution from other languages

Safety drops and speed rises as you go toward NIFs.

1 / 2

Run it: a port and a socket as stand-ins

These are JavaScript stand-ins, not Erlang. First, a port: messages from an "external program" arrive in the owner's mailbox as tagged tuples, and the owner never blocks.

JS Stand-in: a port delivering messages

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Second, active-once flow control: the socket delivers a single message, then waits until the handler re-enables it.

JS Stand-in: active once

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • Using {active, true} on a server that faces many fast clients: memory grows.
  • Forgetting gen_tcp:controlling_process/2: the accepting process still owns the socket, so messages go to the wrong mailbox, and if the acceptor dies the socket closes.
  • Treating TCP as a message stream: without {packet, ...} one recv may return half a message.
  • Long NIFs or leaking resources in NIFs; prefer a port first.
  • Building shell commands with user input in {spawn, Cmd}: use spawn_executable with an argument list to avoid injection.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to the VM if an external program started with open_port crashes?

    Ports isolate the VM from external programs.
  2. 2. What is the main risk of a NIF?

    NIFs run inside the VM's own address space and scheduler threads.
  3. 3. Which socket mode gives per-message flow control?

    {active, once} delivers one message, then waits until you re-enable delivery.
  4. 4. Why call gen_tcp:controlling_process/2 after accept?

    Active-mode messages go to the socket's controlling process, which is the acceptor until transferred.

Summary

  • Ports run external programs through pipes and deliver {Port, {data, Bytes}} messages; a crash there cannot hurt the VM.
  • NIFs are fast native functions with real risk: keep them short or use dirty schedulers.
  • gen_tcp servers spawn one process per connection and transfer socket ownership.
  • Prefer {active, once} or passive mode; frame streams with {packet, N} or {packet, line}.

Next: rebar3 projects