
A VERY BRIEF INTRODUCTION TO MAILBOXES
======================================

To get you started, type

	mbx_server mbx1 &

at a unix prompt of any machine (say `puffin') to start the server.  This
creates a mailbox server program for the mailbox group named `mbx1'.  The
group name must be one of mbx1, mbx2 or mbx3. The machine replies

	MailBoxes Server [mbx1] running on machine puffin

Now start icp and type the Prolog query :

	| ?- ensure_loaded(mailbox).

[ Note that if you are using Parlog, you must execute the same query under
Parlog as well. ]

To connect to the server (which we have named `mbx1' above on the machine
`puffin'), enter the following query (on either Parlog or Prolog) :

	| ?- mbx_init(puffin, mbx1).

Substitute `puffin' and `mbx1' by whatever machine name and group name that
was returned when you started mbx_server.  Thereafter, create mailboxes with

	| ?- mbx_create(ID).

The ID returned is global to all machines connected to the `mbx1' mailbox
group.  i.e. typically multiple machines will have issued the

	| ?- mbx_init(puffin, mbx1).

goal, and thus belong to the `mbx1' mailbox group.  The ID returned can be
used from all the machines to refer to the same mailbox.  In the rest of this
document, <ID> will represent a number returned by a call to mbx_create/1.
To send a message to a mailbox, use

	| ?- mbx_send(<ID>, some_message).

Messages can be sent to mailboxes on any machine connected to the same
mailbox group.  To receive messages, use

	| ?- mbx_recv(<ID>, Msg).

A mbx_recv/2 call blocks if there are no messages in the mailbox.  Again,
messages can be read from any machine in the same group.  As long as a
machine knows the number of a remote mailbox, it can send to and receive
from it.  To find out the number of a remote mailbox that has not been
previously agreed upon, we can query the mailbox server program to see if
it is registered.  To register a mailbox ID we need to supply a name for
it.

	| ?- mbx_bind(<ID>, myname).

Thereafter, other agents may find out the ID of a mailbox by querying the
server,

	| ?- mbx_getid(myname, ID).

or if the number is known but the name isn't, we can use

	| ?- mbx_getname(<ID>, Term).

Note that reading messages is destructive - once it is read, it is
removed from the mailbox.  To read without removing, we use

	| ?- mbx_look(<ID>, Msg).

instead of mbx_recv/2.  Further messages in the mailbox cannot be read
until a decision has been made on whether to remove the `look'ed message.
To remove it, we `commit' the read using

	| ?- mbx_commit(<ID>).

To discard the message so that it can be picked up by another reader, we use

	| ?- mbx_discard(<ID>).

To achieve the effect of one-to-many, many-to-one or even many-to-many
communication, we can use the idea of linked mailboxes.  When mailbox X
is linked to mailbox Y, messages sent to mailbox X will be forwarded
automatically to mailbox Y.  By creating multiple links, multiway
communication is made possible.  To link together two mailboxes, use
the primitive

	| ?- mbx_link(<ID1>, <ID2>).

where messages send to ID1 will appear at ID2.  If we further link
ID1 with ID3, then we have set up a 1-to-2 communication channel.
If instead we linked ID3 to ID2, then we have a 2-to-1 channel.

To break the link between two mailboxes, use

	| ?- mbx_unlink(<ID1>, <ID2>).

The status of a mailbox can be checked using

	| ?- mbx_check(<ID>).

whereupon Status will be bound to one of the following values

	ok	- mailbox has messages
	empty	- mailbox has no messages
	permiss	- the user does not have permission to examine the mailbox
	linked	- mailbox is linked to another one.

To throw away all the current messages in a mailbox, use 

	| ?- mbx_clear(<ID>).

There are three other primitives mbx_initdb/1, mbx_getdb/3 and mbx_closedb/1
which have not been mentioned.  These are used to query the mbx_server when
neither the name or number is known.

Finally, to shutdown a mailbox, issue the command

	| ?- mbx_close(<ID>).

These calls are the simplified forms.  Check the file

	<ICP_INSTALLDIR>/parlog/system/hermes/mailbox.par  or
	<ICP_INSTALLDIR>/prolog/source/mailbox.pl

(where <ICP_INSTALLDIR> is the directory specified in the shell script
/usr/local/bin/icp) for the correct number and ordering of arguments.
