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 3/28/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 3/28/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 3/28/24)