CLERIC reference

Version 0.2.0.

This is the reference document for CLERIC (Common Lisp Erlang Interface). It describes all symbols exported from the CLERIC, and CLERIC-EPMD packages.

The latest version of this document is available here: http://common-lisp.net/project/cleric/doc/cleric_reference.html

The CLERIC package
Types and Classes
Functions
Variables
Conditions

The CLERIC-EPMD package
Functions
Conditions

The CLERIC package

CLERIC is an implementation of the Erlang distribution protocol, making it possible for a Lisp program to act as an Erlang node. Similar libraries exist for other languages; erl_interface for C and jinterface for Java are part of the official Erlang distribution.

Types and Classes

[Type]
erlang-translatable

The type erlang-translatable contains all types of Lisp objects that may be translated to Erlang objects.

[Standard class]
erlang-binary

Represents an Erlang binary.

[Standard class]
erlang-external-fun

Represents an Erlang external fun.

[Standard class]
erlang-new-internal-fun

Represents an Erlang 'new' internal fun.

[Standard class]
erlang-old-internal-fun

Represents an Erlang internal fun.

[Standard class]
erlang-pid

Represents an Erlang Pid.

[Standard class]
erlang-port

Represents an Erlang Port.

[Standard class]
erlang-reference

Represents an Erlang reference.

[Standard class]
erlang-tuple

Represents an Erlang tuple.


[Standard class]
remote-node

Represents a remote Erlang node.

[Standard class]
exit

Exit message object.

[Standard class]
exit2

Exit2 message object.

[Standard class]
group-leader

Group leader message object.

[Standard class]
link

Link message object.

[Standard class]
node-link

Node link message object.

[Standard class]
reg-send

Reg send message object.

[Standard class]
send

Send message object.

[Standard class]
unlink

Unlink message object.

Functions

[Generic function]
arity tuple-or-fun => arity

Returns the arity of tuple-or-fun. For tuples that means the number of elements and for Funs the number of arguments.


[Function]
binary &rest bytes => binary

Creates a new binary from bytes.


[Function]
binary-to-string binary => string

Converts binary to a string.


[Generic function]
bits-in-last-byte binary => number-of-bits

Returns the number of bits used in the last byte of binary.

[Generic function]
bytes binary => bytes

Returns a vector of bytes from binary.


[Function]
bytes-to-binary bytes => binary

Creates a new binary from the byte sequence bytes.


[Function]
connected-remote-nodes => node-names

Returns a list of all the currently connected remote nodes.

[Generic function]
cookie control-message => cookie

Returns the cookie in control-message.

[Function]
decode bytes &key start version-tag => erlang-term, position

start defaults to 0.
version-tag defaults to NIL.

Decodes the sequence bytes into Erlang terms, starting from position start. position is the number of bytes consumed from bytes. If version-tag is true, bytes is expected to begin with a version tag.

[Generic function]
elements tuple => elements

Returns a vector with the elements in tuple.


[Generic function]
encode erlang-translatable-object &key version-tag atom-cache-entries => bytes

version-tag defaults to NIL.
atom-cache-entries defaults to NIL.

Encodes erlang-translatable-object into a sequence of bytes. If version-tag is true, bytes will start with a version tag.

[Function]
erlang-translatable-p object => boolean

Returns true if object can be encoded to an Erlang term.

[Generic function]
from-pid control-message => pid

Returns the Pid from which control-message was sent.

[Function]
link from-pid to-pid => NIL

Establish a process link between from-pid and to-pid. Sends a Link control message to the node where the process to-pid is located.

[Function]
listening-p => boolean

Returns true if currently listening on a server socket.

[Function]
listening-port => port

Returns the port number of the listening (server) socket. Returns NIL if not listening on a socket.

[Function]
make-atom string => symbol

Creates a symbol with name string which is interned in the package defined by *atom-symbol-package*.

[Function]
make-pid => pid

Creates a Pid object. Useful for sending and receiving messages.

[Function]
make-reference => reference

Creates a unique Reference object.

[Function]
match-p object-a object-b => boolean

Returns true if object-a and object-b match.

[Generic function]
message control-message => message

Returns the message part of control-message.

[Generic function]
module erlang-fun => symbol

Returns the module of erlang-fun.

[Generic function]
node erlang-identifier => symbol

Returns the node of erlang-identifier. An Erlang identifier is either a Pid, Port, or a reference object.

[Function]
node-name full-node-name => name

Returns the short node name from full-node-name.

[Function]
node-host full-node-name => host

Returns the node hostname from full-node-name.

[Generic function]
reason exit-control-message => term

Returns the reason of exit-control-message.

[Function]
receive-node-messages &key timeout => control-messages

timeout defaults to NIL.

Waits for and receives messages from connected nodes. Returns a list of received messages.


[Function]
reg-send from-pid to-name node message => NIL

Sends message from from-pid to registered process to-name on node.

[Function]
remote-node-accept-connect cookie => full-node-name

Accept connection from a remote node and perform handshake using cookie.

If the handshake is successful, the node is registered and the full node name is returned.


[Function]
remote-node-connect remote-node cookie => t

Connect and perform handshake with remote-node. If the connection and handshake is successful the node is registered and the full node name is returned.


[Generic function]
remote-node-host remote-node => host-string

Returns the host where remote-node is located.

[Generic function]
remote-node-name remote-node => node-name

Returns the node name of remote-node.

[Generic function]
remote-node-port remote-node => port-number

Returns the port on which remote-node listens.

[Generic function]
remote-node-socket remote-node => socket-object

Returns the usocket socket object used for communicating with remote-node.

[Function]
send to-pid message => NIL

Sends message to to-pid.

[Generic function]
size tuple-or-binary => size

Returns the size of tuple-or-binary which means the number of elements in a tuple or the number of bytes in a binary.


[Function]
start-listening => T

Opens a listening (server) socket to which other nodes may connect.

To accept connections from remote nodes, use remote-node-accept-connect


[Function]
start-listening-on-socket-restart condition => T

Invokes the start-listening-on-socket restart.

condition is ignored.


[Function]
stop-listening => NIL

Closes the listening (server) socket.

[Function]
string-to-binary string => binary

Creates a new binary from string.


[Function]
this-node => local-node-name

setf-able function.

Returns the local node name.


[Generic function]
to-name reg-send-control-message => registered-name

Returns the registered process name of the receiver of reg-send-control-message.

[Generic function]
to-pid control-message => pid

Returns the receiving Pid of control-message.

[Generic function]
trace-token control-message => trace-token

Returns the trace token of control-message.

[Function]
try-again-condition-p condition => boolean

Returns true if condition is of type try-again.

[Function]
try-connect-again-restart condition => T

Invokes the try-connect-again restart.

condition is ignored.


[Function]
tuple &rest objects => tuple

Creates a new tuple containing objects.


[Function]
unlink from-pid to-pid => NIL

Unlinks from-pid and to-pid. Sends an Unlink control message to the node where to-pid is located.

Variables

[Special variable]
*atom-symbol-package*

Initial value: :KEYWORD

Defines the package in which new symbols sent from remote nodes will be interned.


[Special variable]
*erlang-false-is-lisp-nil*

Initial value: NIL

When true, the symbol |false| received from a remote node will be translated to NIL.


[Special variable]
*erlang-string-is-lisp-string*

Initial value: NIL

When true, a string received from a remote node will be translated to a string instead of a list of integers.


[Special variable]
*erlang-true-is-lisp-t*

Initial value: NIL

When true, the symbol |true| received from a remote node will be translated to T.


[Special variable]
*lisp-nil-at-tail-is-erlang-empty-list*

Initial value: T

When true, translate NIL at the tail of a list to an empty list when sending to a remote node.

Note: You will most likely never need to change this variable.


[Special variable]
*lisp-nil-is-erlang-empty-list*

Initial value: T

When true, translate a non-tail NIL to an empty list when sending to a remote node.


[Special variable]
*lisp-nil-is-erlang-false*

Initial value: NIL

When true, translate a non-tail NIL to the symbol |false| when sending to a remote node.


[Special variable]
*lisp-string-is-erlang-binary*

Initial value: NIL

When true, translate a string to a binary when sending to a remote node.


[Special variable]
*lisp-t-is-erlang-true*

Initial value: NIL

When true, translate T to the symbol |true| when sending to a remote node.


[Constant variable]
+highest-version-supported+

Value: 5

[Constant variable]
+lowest-version-supported+

Value: 5

Conditions

[Condition]
already-listening-on-socket


[Condition]
connection-closed-error


[Condition]
handshake-failed-error


[Condition]
malformed-external-erlang-term-error


[Condition]
malformed-message-error


[Condition]
node-unreachable-error


[Condition]
not-implemented-error


[Condition]
not-listening-on-socket


[Condition]
try-again


[Condition]
unexpected-message-length-error


[Condition]
unexpected-message-tag-error


[Condition]
untranslatable-lisp-object-error



The CLERIC-EPMD package

The CLERIC-EPMD package contains functions and other symbols related to querying the Erlang Port Mapper Daemon (EPMD).

Functions

[Function]
lookup-node node-name &optional host => remote-node

host defaults to "localhost".

Queries the EPMD at host for node node-name. If the node exists, a remote-node object is returned representing that node. Otherwise NIL is returned.


[Function]
print-all-registered-nodes &optional host stream => T

host defaults to "localhost".
stream defaults to T.

Print to stream the names and listening port for all nodes registered on the EPMD at host.

[Function]
publish => T

Register on the EPMD to become visible to remote nodes.

[Function]
published-p => boolean

Returns true if registered on the EPMD.

[Function]
unpublish => T

Unregister from the EPMD to stop being visible to remote nodes.

Conditions

[Condition]
already-registered


[Condition]
host-unknown-error


[Condition]
response-error


[Condition]
unreachable-error