ref: 75c92428225428c8fde2d015f010e608a0b12f1d
dir: purgatorio/man/4/spree
.TH SPREE 4
.SH NAME
spree \- distributed interactive sessions.
.SH SYNOPSIS
.B mount {spree/spree} /n/remote
.PP
.B /n/remote/name
.br
.BI /n/remote/ n
.br
.BI /n/remote/ n /ctl
.SH DESCRIPTION
.B Spree
serves a file system that allows clients to interact
through various types of
.I engine
(see
.IR spree (2)
for an explanation of engines).
It serves styx messages through file descriptor 0;
thus it can be mounted directly with
.IR mount (1),
or made available across the network
with
.I styxlisten
(see
.IR listen (1)).
.PP
Spree serves a name-space consisting of a directory
for each clique that is currently active, and
a file,
.BR name ,
that holds the authenticated name of the user that has
mounted the spree namespace.
A clique's directory holds at least one file,
.BR 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
.BR join ,
but some engines accept other kinds of message
(e.g.
.BR 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
.RB ( * )
respectively, indicating that there are more updates
to come.
.PP
When
.I spree
is first started, it creates one clique, a ``lobby''
(see
.IR spree-lobby (4))
that allows other cliques to be created; this
is named
.BR 0 ).
.PP
A client cannot join a particular clique
more than once.
.PP
A zero-length write to the
.B 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.
.PP
The update messages generated by
.I spree
are as follows:
.RS
.TP
.BI create " objid parentid visibility objtype"
Create an object, identified by
.IR objid ,
at the end of
.IR parentid 's
children
.RI ( parentid
is
.B -1
for the root object).
.I Visibility
is non-zero if the object's children are visible
to the member reading the update.
.I Objtype
is the object's type (engine dependent).
.TP
.BI tx " srcid dstid start end index"
Transfer objects from
.I srcid
to
.IR dstid.
Take the objects from the range
.RI [ start ,\ end )
in the children of
.IR srcid ,
and insert them just before
.I index
in
.IR 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
.I 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.
.TP
.BI del " parentid start end " "" objid\fR...
Delete the range
.RI [ start ,\ end )
of children from the object identified by
.IR parentid .
.I Spree
guarantees that those objects will themselves
not have any children.
The list of
.IR objid s
gives the actual identifiers of the objects deleted,
for the benefit of clients that do not wish to keep lists of objects' children.
.TP
.BI set " objid attr val"
Set the attribute named
.I attr
on object
.I objid
to
.IR val .
.TP
.BI vis " objid visibility"
The visibility of object to the reading member
.I objid
has changed to
.I visibility
(non-zero if visible).
.TP
.I action
Game engines can generate arbitrary messages
of their own devising; such messages are specific
to particular engine types.
.PP
Note that a given client does not have to interpret
all the above messages \- different client types
have their own conventions. The
.B card
client type uses most of the above functionality,
for example, whereas a client for the
.B chat
engine listed in
.IR spree (2)
can get away with interpreting only one message, the custom action
.BR chat .
.PP
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.
.RE
.SH EXAMPLE
The simplest client!
.PP
.EX
mount tcp!somehost.com!3242 /n/remote
{
echo create chat >[1=0]
cat &
cat >[1=0] < /dev/cons
} <> /n/remote/new
.SH SOURCE
.B /appl/cmd/cliques/spree.b
.SH SEE ALSO
.IR spree (2)