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 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 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 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 parentid's children (parentid is -1 for the root object). Visibility is non-zero if the object's children are visible 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 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)

SPREE(4 )

Rev:  Tue Mar 31 02:42:39 GMT 2015