diff options
Diffstat (limited to 'man/4/spree')
| -rw-r--r-- | man/4/spree | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/man/4/spree b/man/4/spree new file mode 100644 index 00000000..f4541e1d --- /dev/null +++ b/man/4/spree @@ -0,0 +1,195 @@ +.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) |