SPREE(4) SPREE(4)
NAME
spree - distributed interactive sessions.
SYNOPSIS
mount {spree/spree} /n/remote
/n/remote/name
/n/remote/n
/n/remote/n/ctl
DESCRIPTION
Spree serves a file system that allows clients to interact
through various types of engine (see spree(2) for an expla-
nation of engines). It serves styx messages through file
descriptor 0; thus it can be mounted directly with mount(1),
or made available across the network with styxlisten (see
listen(1)).
Spree serves a name-space consisting of a directory for each
clique that is currently active, and a file, name, that
holds the authenticated name of the user that has mounted
the spree namespace. A clique's directory holds at least
one file, ctl; if a client opens this file, it can write to
it communicate with the clique's engine, and read from it to
find updates to the state of the clique. Messages written
to the file are formed as text and the write yields an error
if there is an error executing the command. The first mes-
sage written to the file is the initial request to join the
clique; conventionally it is the string join, but some
engines accept other kinds of message (e.g. watch). If the
initial request succeeds, the client will be informed of the
current state of the clique by means of update messages read
from the same file. Reading from the file will block until
an update is available, whereupon the read request will
return as many updates are available, separated by newline
characters. If there are more updates available than can
fit in the read request, the last two bytes of the buffer
read will be a newline character and an asterisk (*) respec-
tively, indicating that there are more updates to come.
When spree is first started, it creates one clique, a
``lobby'' (see spree-lobby(4)) that allows other cliques to
be created; this is named 0).
A client cannot join a particular clique more than once.
A zero-length write to the ctl file causes any reads of that
file from the same file descriptor to yield EOF (no bytes).
This is necessary to force a hangup under systems such as
Windows, where it is not possible to interrupt a kproc
Page 1 Plan 9 (printed 12/22/24)
SPREE(4) SPREE(4)
blocked on a network read.
The update messages generated by spree are as follows:
create objid parentid visibility objtype
Create an object, identified by objid, at the end
of parentid's children (parentid is -1 for the
root object). Visibility is non-zero if the
object's children are visible to the member read-
ing the update. Objtype is the object's type
(engine dependent).
tx srcid dstid start end index
Transfer objects from srcid to dstid. Take the
objects from the range [start, end) in the chil-
dren of srcid, and insert them just before index
in dstid. When objects are transferred to an
object that conceals its children, and the object
is itself visible, the objects will first be
transferred to the destination and then deleted;
objects transferred out of such an object will
first be created and then transferred to their
destination. This enables a client to maintain
some knowledge of where an object has been trans-
ferred to, even if the object is no longer visi-
ble, and means that a client is unable to keep
track of objects that are concealed from it.
del parentid start end
Delete the range [start, end) of children from the
object identified by parentid. Spree guarantees
that those objects will themselves not have any
children. The list of objids gives the actual
identifiers of the objects deleted, for the bene-
fit of clients that do not wish to keep lists of
objects' children.
set objid attr val
Set the attribute named attr on object objid to
val.
vis objid visibility
The visibility of object to the reading member
objid has changed to visibility (non-zero if visi-
ble).
action
Game engines can generate arbitrary messages of
their own devising; such messages are specific to
particular engine types.
Note that a given client does not have to interpret all
Page 2 Plan 9 (printed 12/22/24)
SPREE(4) SPREE(4)
the above messages - different client types have their
own conventions. The card client type uses most of the
above functionality, for example, whereas a client for
the chat engine listed in spree(2) can get away with
interpreting only one message, the custom action chat.
Writes to the opened clique file are interpreted as
clique actions by the clique that has been loaded, and
acted on accordingly. Invalid actions will draw a
write error.
EXAMPLE
The simplest client!
mount tcp!somehost.com!3242 /n/remote
{
echo create chat >[1=0]
cat &
cat >[1=0] < /dev/cons
} <> /n/remote/new
SOURCE
/appl/cmd/cliques/spree.b
SEE ALSO
spree(2)
Page 3 Plan 9 (printed 12/22/24)