What is difference between {active, false}, {active, true} and {active, once}?

Question

as you probably know, there three modes of gen_tcp. {active, false}, {active, true} and {active, once}.

I have read some documents about {active, false}, {active, true} and {active, once}. However, I didn't get it.

What is difference between {active, false} and {active, true} and {active, once}?

Could you please explain plainly?

Answer 1

{active, false}
You have to read a chunk of data from the socket by calling gen_tcp:recv().

{active, true}
Erlang automatically reads chunks of data from the socket for you and gathers the chunks into a complete message and puts the message in the process mailbox. You read the messages using a receive clause. If some hostile actor floods your mailbox with messages, your process will crash.

{active, once}
Equivalent to {active, true} for the first chunks of data read from the socket, then {active, false} for any subsequent chunks of data.

You also need to understand how specifying {packet, N} influences things. See here: Erlang gen_tcp not receiving anything.

Answer 2

It's about flow control: you have an Erlang process handling incoming network traffic. Usually you want it to react to incoming packets quickly, but you don't want its queue of messages to grow faster than it can process it - but in certain cases you'll have different goals.

With {active, false}, you have explicit control of when the process receives incoming traffic: it only happens when you call gen_tcp:recv. However, while the process is waiting in gen_tcp:recv, it cannot receive other Erlang messages. Perhaps some other Erlang process is sending a message telling it to stop, but it doesn't know that yet because it's concentrating on getting network input.

With {active, true}, network input gets sent to the process as a message as soon as it is available. That means that you could have a receive expression that expects both network traffic and simple Erlang messages from other processes. This mode of operation could be useful if you're confident that your process can handle the input faster than it arrives, but you could end up with a long message queue that never gets cleared.

{active, once} is a compromise between the two: you receive incoming data as Erlang messages, meaning that you can mix network traffic with other work, but after receiving a packet you need to explicitly call inet:setopts with {active, once} again to receive more data, so you get to decide how quickly your process receives messages.

Since Erlang/OTP 17.0 there is yet another option, {active, N}, where N is an integer. That means that you can receive N messages before you have to call inet:setopts again. That could give higher throughput without having to give up flow control.