Enm

enm is an Erlang port driver that wraps the nanomsg C library, allowing Erlang systems to communicate with other nanomsg endpoints. enm supports idioms and approaches common to standard Erlang networking facilities such as gen_tcp and gen_udp.

enm is currently based on version 1.0.0 of nanomsg, and enm itself is new, so its features are experimental and subject to change.

Starting and Stopping

You can start enm as a normal application, using application:start(enm) and application:stop(enm). You can also call enm:start_link/0 or enm:start/0, and call enm:stop/0 to stop it.

Just Open a Socket

enm supports all nanomsg scalability protocols and transports. You can open a socket providing a particular scalability protocol using functions named for each protocol. For example, the enm:pair/0 function opens a pair-type socket for one-to-one communication, and the enm:req/0 and enm:rep/0 functions open the request and reply ends, respectively, of the reqrep scalability protocol. The arity 0 versions of the enm scalability protocol functions listed below use default settings for the open sockets, while the arity 1 versions allow a list of socket options to be passed in order to control socket settings.

• req: open the request end of the reqrep protocol
• rep: open the reply end of the reqrep protocol
• pair: open a pair socket for one-to-one communications
• bus: open a bus socket for many-to-many communications
• pub: open the publication end of the pubsub protocol
• sub: open the subscriber end of the pubsub protocol
• push: open the pushing end of the pipeline protocol
• pull: open the pulling end of the pipeline protocol
• surveyor: open the query end of the survey protocol
• respondent: open the response end of the survey protocol

If successful, these functions — both their arity 0 and arity 1 versions — all return {ok,Socket}.

Once opened, sockets can be bound or connected using the enm:bind/2 or enm:connect/2 functions respectively. Bind and connect information can alternatively be provided via socket options when sockets are first opened via the functions listed above.

Functions

In addition to the scalability protocol functions, enm supports the following functions:

• send(Socket, Data): send Data on Socket. Data is an Erlang iolist, thus allowing lists of binaries and characters, or nested lists thereof, to be sent.
• recv(Socket): receive data from Socket. This function blocks indefinitely until data arrive. Returns {ok,Data} on success, or an error tuple on failure. Data defaults to a binary unless the socket was opened in list mode or was set into list mode via setopts/2.
• recv(Socket, Timeout): same as recv/1 but if no data arrive within Timeout milliseconds, return {error,etimedout}.
• bind(Socket, Address): bind Socket to Address, where Address supports one of the nanomsg transport types: inproc, ipc, or TCP. Address can be either a string or binary using the nanomsg URL address format, such as "inproc://foo" to bind to an intraprocess address or "tcp://*:12345" to listen on all your host's network interfaces on port 12345, or it can be one of the enm address record types.
• getopts(Socket, Options): return the current setting on Socket for each of the option names listed in Options. If successful, returns {ok, OptionList} where each element of the list provides the name and setting of one of the requested options. If getopts fails it return an error tuple.
• setopts(Socket, OptionList): apply each of the option settings in OptionList to Socket. Returns ok if successful or an error tuple on failure.
• controlling_process(Socket, Pid): the current controlling process for Socket can call this function to transfer its control to the process represented by Pid. The controlling process of a Socket is initially the one that opens it, and it's the one that receives data messages as Erlang messages if the socket is in an active mode.
• shutdown(Socket, EndpointId): removes the endpoint associated with EndpointId, created via bind/2 or connect/2, from Socket.
• close(Socket): closes Socket.

If you're already familiar with standard Erlang networking capabilities, you'll find these functions similar to functions supplied by standard modules such as gen_tcp, gen_udp and inet.

Address Record Types

To help avoid errors with mistyped string and binary address URLs, enm provides three record types you can use for addresses instead:

• #nn_inproc{addr=Address}: for intra-process addresses. Address is a name in either string or binary form.
• #nn_ipc{path=Path}: for IPC addresses. Path can be either an absolute pathname or a pathname relative to the current working directory, in either string or binary form.
• #nn_tcp{interface=Interface, addr=Address, port=Port}: for TCP addresses. Interface can be the atom any, a network address in string or tuple form, or a string representing a network interface name. Address can be a hostname or a network address in either string or binary form. Port is a port number.

Using these types, which is completely optional, requires including the enm.hrl file.

Socket Options

enm supports several socket options that can be set either when the socket is opened, or modified later during operation. Most socket options can also be read from enm sockets. enm supports the following options:

• type: indicates the type of socket. For example, the nnreq type indicates a socket opened via the req function, and nnsurveyor indicates a socket implementing the query end of the survey protocol. This option can only be read from an enm socket and cannot be set.
• active: this controls how messages are delivered from an enm socket to its controlling Erlang process.
  • The default setting, {active,true}, means that the driver reads data from the socket as soon as they arrive and sends them as Erlang messages to the controlling process.
  • The {active,false} setting puts an enm socket in passive mode; data from such a socket are retrieved only via the enm:recv/{1,2} functions.
  • The {active,once} setting allows the driver to deliver one message from the socket to the controlling process, after which the socket flips automatically to {active,false} mode. This allows the application to receive nanomsg messages as Erlang messages only when it's ready to handle them.
  • The {active,N} mode, where N represents an integer, is similar to {active,once} mode except that it allows the driver to receive N messages on the socket and deliver them as Erlang messages to the controlling process before flipping the socket into {active,false} mode. When the socket flips to passive mode, enm sends a {X_passive,Socket} message to the controlling process, with the socket's actual type name substituted for "X" (for example, {nnpair_passive, Socket} if Socket is a pair socket).
• raw: this option, which defaults to false, controls whether the underlying nanomsg socket is opened with the AF_SP domain (the default, or set via {raw,false}) or the AF_SP_RAW domain (set via {raw,true}). Using the atom raw by itself is equivalent to {raw,true}. See the nanomsg nn_socket man page for more details on the AF_SP and AF_SP_RAW socket domains.
• mode: this controls the form of the data delivered or retrieved from the socket. The default, binary, means that data from the socket are delivered to the application as Erlang binaries, whereas the list setting means socket data are delivered as Erlang lists. Using the atom binary by itself is equivalent to {mode,binary}, and list by itself is equivalent to {mode,list}.
• bind: this option allows you to open a socket and then immediately bind it to the given address. See the bind function description for more details on the allowable forms for the bind address. Note, however, that the bind endpoint identifier is thrown away in this case. If you need to later manage the endpoint via shutdown, use the bind function instead.
• connect: this option allows you open a socket and then immediately connect it to the given address. See the connect function description for more details on the allowable forms for the connect address. Note, however, that the connect endpoint identifier is thrown away in this case. If you need to later manage the endpoint via shutdown, use the connect function instead.
• deadline: for surveyor sockets, set the surveyor deadline to specify how long, in milliseconds, to wait for responses to arrive.
• subscribe: for sub sockets, subscribe to the named topic, specified either as a string or a binary. Topic names must be less than 256 characters in length (this is an enm limit, not a nanomsg limit). Applying the subscribe option to a socket type other than sub results in a badarg exception.
• unsubscribe: for sub sockets, unsubscribe from the named topic, specified either as a string or a binary. As for the subscribe option, topic names must be less than 256 characters in length. Applying the unsubscribe option to a socket type other than sub results in a badarg exception.
• resend_ivl: for req sockets, set the request resend inter