SPREE(4)SPREE(4)NAMEspree - 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 var‐
ious types of engine (see spree(2) for an explanation 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 authenti‐
cated 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 message 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 (*)
respectively, 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 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 par‐
entid's children (parentid is -1 for the root object).
Visibility is non-zero if the object's children are visi‐
ble to the member reading 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 children 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 transferred to, even if the object is no longer
visible, and means that a client is unable to keep track
of objects that are concealed from it.
del parentid start end objid...
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 benefit 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 visible).
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 the
above messages - different client types have their own conven‐
tions. The card client type uses most of the above functional‐
ity, 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 accord‐
ingly. 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 ALSOspree(2)SPREE(4)
