Project

Topics

Namespaces

Clojang User’s Guide: The Low-level API

The JInterface Package in Clojang

NOTICE: This document is a copy of the JInterface Users Guide, a version of which is provided in the published documentation for the Clojang project.

The Jinterface package provides a set of tools for communication with Erlang processes. It can also be used for communication with other Java processes using the same package, as well as C processes using the Erl_Interface library.

The set of classes in the package can be divided into two categories: those that provide the actual communication, and those that provide a Java representation of the Erlang data types. The latter are all subclasses of OtpErlangObject, and they are identified by the OtpErlang prefix.

Since this package provides a mechanism for communicating with Erlang, message recipients can be Erlang processes or instances of com.ericsson.otp.erlang.OtpMbox, both of which are identified with pids and possibly registered names. When pids or mailboxes are mentioned as message senders or recipients in this section, it should assumed that even Erlang processes are included, unless specified otherwise. The classes in Jinterface support the following:

  • manipulation of data represented as Erlang data types
  • conversion of data between Java and Erlang formats
  • encoding and decoding of Erlang data types for transmission or storage
  • communication between Java nodes and Erlang processes

In the following sections, these topics are described:

  • mapping of Erlang types to Java
  • encoding, decoding, and sending Erlang terms
  • connecting to a distributed Erlang node
  • using nodes, mailboxes and EPMD
  • sending and receiving Erlang messages and data
  • remote procedure calls
  • linking to remote processes
  • compiling your code for use with Jinterface
  • tracing message flow

http://oubiwann.github.io/clojang/current/clojang.jinterface.erlang.types.html#var-atom

Mapping of Basic Erlang Types to the JVM

This section describes the mapping of Erlang basic types to JVM types.

Erlang type JVM type
atom atom
binary OtpErlangBinary
floating point types OtpErlangFloat or OtpErlangDouble, depending on the floating point value size
integral types One of OtpErlangByte, char,OtpErlangShort, OtpErlangUShort,OtpErlangInt,OtpErlangUInt or OtpErlangLong, depending on the integral value size and sign
list list
pid OtpErlangPid
port OtpErlangPort
ref OtpErlangRef
tuple tuple
map OtpErlangMap
term OtpErlangObject

Special Mapping Issues

The atoms true and false are special atoms, used as boolean values. The class boolean can be used to represent these.

Lists in Erlang are also used to describe sequences of printable characters (strings). A convenience class string is provided to represent Erlang strings.

Nodes

A node as defined by Erlang/OTP is an instance of the Erlang Runtime System, a virtual machine roughly equivalent to a JVM. Each node has a unique name in the form of an identifier composed partly of the hostname on which the node is running, e.g gurka@sallad.com. Several such nodes can run on the same host as long as their names are unique. The class node represents an Erlang node. It is created with a name and optionally a port number on which it listens for incoming connections. Before creating an instance of node, ensure that EPMD is running on the host machine. See the Erlang documentation for more information about EPMD. In this example, the host name is appended automatically to the identifier, and the port number is chosen by the underlying system:

=> (require '[clojang.jinterface.otp.nodes :as nodes])
nil
=> (def gurka (nodes/node "gurka"))
#'user/node

Mailboxes

Erlang processes running on an Erlang node are identified by process identifiers (pids) and, optionally, by registered names unique within the node. Each Erlang process has an implicit mailbox that is used to receive messages; the mailbox is identified with the pid of the process.

JInterface provides a similar mechanism with the class OtpMbox, a mailbox that can be used to send and receive messages asynchronously. Each OtpMbox is identified with a unique pid and , optionally, a registered name unique within the OtpMbox.

Applications are free to create mailboxes as necessary. This is done as follows:

user=> (def mbox (nodes/create-mbox gurka))
#'user/mbox

or like this:

=> (require '[clojang.jinterface.otp.messaging :as messaging])
nill
user=> (def mbox (messaging/mbox gurka))
#'user/mbox

The mailbox created in the above example has no registered name, although it does have a pid. The pid can be obtained from the mailbox and included in messages sent from the mailbox, so that remote processes are able to respond.

An application can register a name for a mailbox, either when the mailbox is initially created:

user=> (def mbox (nodes/create-mbox gurka "server"))
#'user/mbox

or later on, if need be. You may either use the register-mbox function for the Node):

=> (nodes/register-mbox gurka "server2" mbox)
true

or the register-name function for the Mbox:

=> (messaging/register-name mbox "server3")
true

Registered names are usually necessary in order to start communication, since it is impossible to know in advance the pid of a remote process. If a well-known name for one of the processes is chosen in advance and known by all communicating parties within an application, each mailbox can send an initial message to the named mailbox, which then can identify the sender pid.

Connections

It is not necessary to explicitly set up communication with a remote node. Simply sending a message to a mailbox on that node will cause the OtpNode to create a connection if one does not already exist. Once the connection is established, subsequent messages to the same node will reuse the same connection.

It is possible to check for the existence of a remote node before attempting to communicate with it. Here we send a ping message to the remote node to see if it is alive and accepting connections. Paste the following function in your REPL:

(defn print-liveliness [node other]
  (if (nodes/ping node other 1000)
    (println "It's aliiiive!")
    (println "Mate, this node wouldn't go 'voom' if ...")))

Now let’s use it:

user=> (print-liveliness gurka "gurka")
It's aliiiive!
nil
user=> (print-liveliness gurka "nohost")
Mate, this node wouldn't go 'voom' if ...
nil

If the call to (nodes/ping ...) succeeds, a connection to the remote node has been established. Note that it is not necessary to ping remote nodes before communicating with them, but by using ping you can determine if the remote exists before attempting to communicate with it.

Connections are only permitted by nodes using the same security cookie. The cookie is a short string provided either as an argument when creating node objects, or found in the user’s home directory in the file .erlang.cookie. When a connection attempt is made, the string is used as part of the authentication process. If you are having trouble getting communication to work, use the trace facility (described later in this document) to show the connection establishment. A likely problem is that the cookies are different.

Connections are never broken explicitly. If a node fails or is closed, a connection may be broken however.

Transport Factory

All necessary connections are made using methods of OtpTransportFactory interface. Default OtpTransportFactory implementation is based on standard Socket class. User may provide custom transport factory as needed. See java doc for details.

Sending and Receiving Messages

Messages sent with this package must be instances of object or one of its subclasses. Message can be sent to processes or pids, either by specifying the pid of the remote, or its registered name and node.

In this example, we create a message containing our own pid so the echo process can reply:

=> (require '[clojang.jinterface.erlang.types :as types])
nil
=> (def msg (into-array (types/object) [(messaging/self mbox)
                                        (types/atom "hello, world")]))
#'user/msg
=> (messaging/register-name mbox "echo")
true
=> (messaging/send mbox "echo" "gurka" (types/tuple msg))
nil
=> (messaging/receive mbox)
#object[com.ericsson.otp.erlang.OtpErlangTuple
        0xeed771a
        "{#Pid<gurka@mndltl01.1.0>,'hello, world'}"]

You can also send messages from Erlang VMs to your node’s mailbox named "echo". Before you do that, though, start listening in your Clojure REPL:

=> (messaging/receive mbox)

Next, start up LFE (Lisp Flavoured Erlang) on the same machine with a short name:

$ /path/to/bin/lfe -sname lfe
LFE Shell V7.2 (abort with ^G)
(clojang-lfe@mndltl01)>

Once you’re in the REPL, you’re ready to send a message:

(clojang-lfe@mndltl01)> (! #(echo gurka@mndltl01) #(hej!))
#(hej!)

Looking at the Clojure REPL, you’ll see that your receive call has finished and you now have some data:

#object[com.ericsson.otp.erlang.OtpErlangTuple 0x4a377f4e "{'hej!'}"]

Sending Arbitrary Data

TBD

Linking to Remote Processes

TBD

Using EPMD

TBD

Remote Procedure Calls

An Erlang node acting as a client to another Erlang node typically sends a request and waits for a reply. Such a request is included in a function call at a remote node and is called a remote procedure call. Remote procedure calls are supported through the connection Clojure protocol. The following example shows how the connection protocol is used for remote procedure calls:

(require '[clojang.jinterface.otp.connection :as connection])
(def self (nodes/self "client"))
(def other (nodes/peer "clojang-lfe@mndltl01"))
(def connx (nodes/connect self other))

(connection/!rpc connx "erlang" "date" (types/list))
(connection/receive-rpc connx)
#object[com.ericsson.otp.erlang.OtpErlangTuple 0x385465c1 "{2016,1,30}"]