20060303-partial

1 files changed, 604 insertions, 0 deletions

diff --git a/man/2/spree b/man/2/spree
new file mode 100644
index 00000000..1cd517b3
--- /dev/null
+++ b/man/2/spree
@@ -0,0 +1,604 @@
+.TH SPREE 2
+.SH NAME
+Spree \- distributed interactive sessions.
+.SH SYNOPSIS
+.EX
+.ps -1
+.vs -1
+include "sys.m";
+include "draw.m";
+include "sets.m";
+include "spree.m";
+spree := load Spree Spree->PATH;
+Range, Object, Clique, Member: import spree;
+Set: import Sets;
+Archive: import Archives;
+
+Range: adt {
+    start:  int;
+    end:    int;
+};
+
+Object: adt {
+    transfer:           fn(o: self ref Object,
+            r: Range, dst: ref Object, i: int);
+    setvisibility:      fn(o: self ref Object,
+            visibility: Set);
+    setattrvisibility:  fn(o: self ref Object,
+            name: string, visibility: Set);
+    setattr:        fn(o: self ref Object,
+            name: string, val: string, vis: Set);
+    getattr:        fn(o: self ref Object, name: string): string;
+    delete:     fn(o: self ref Object);
+    deletechildren: fn(o: self ref Object, r: Range);
+
+    id:     int;
+    parentid:   int;
+    children:   array of ref Object;
+    objtype:    string;
+    visibility: Set;
+    # ...private data
+};
+
+Clique: adt {
+    new:       fn(parent: self ref Clique, archive: ref Archive,
+				owner: string): (int, string, string);
+    newobject: fn(clique: self ref Clique, parent: ref Object,
+            visibility: int, objtype: string): ref Object;
+    action:   fn(clique: self ref Clique, cmd: string,
+               objs: list of int, rest: string, whoto: int);
+    member:   fn(clique: self ref Clique, id: int): ref Member;
+    start:    fn(clique: self ref Clique);
+    breakmsg: fn(clique: self ref Clique, whoto: Sets->Set);
+    members:  fn(clique: self ref Clique): list of ref Member;
+    owner:    fn(clique: self ref Clique): string;
+    hangup:   fn(clique: self ref Clique);
+    notify:   fn(clique: self ref Clique, cliqueid: int, msg: string);
+
+    objects:  array of ref Object;
+    cliqueid: int;
+    # ...private data
+};
+
+Member: adt {
+    obj:    fn(m: self ref Member, id: int): ref Object;
+    del:    fn(m: self ref Member, suspend: int);
+
+    id:     int;
+    name:   string;
+    # ...private data
+};
+
+Engine: module {
+	init:			fn(srvmod: Spree, clique: ref Clique, argv: list of string): string;
+	command:	fn(member: ref Member, e: string): string;
+	join:			fn(member: ref Member , e: string, suspended: int): string;
+	leave:		fn(member: ref Member): int;
+	notify:		fn(fromid: int, s: string);
+	readfile:		fn(f: int, offset: big, count: int): array of byte;
+};
+
+Archives: module {
+	Archive: adt {
+		argv:		list of string;			# how to restart the session.
+		members:	array of string;			# members involved.
+		info:		list of (string, string);	# any other information.
+		objects:	array of ref Object;
+	};
+	init:			fn(mod: Spree);
+	write:		fn(clique: ref Clique, info: list of (string, string), file: string, members: Set): string;
+	read:			fn(file: string): (ref Archive, string);
+	readheader:	fn(file: string): (ref Archive, string);
+};
+
+rand:   fn(n: int): int;
+.ps +1
+.vs +1
+.EE
+.SH DESCRIPTION
+.I Spree
+provides a general server interface that allows sets of distributed
+clients,
+.IR cliques ,
+to interact in a controlled manner, with the
+interaction mediated
+by Limbo modules, known as
+.IR engines .
+Each engine decides on the rules
+of its particular clique; the engine interface is described
+at the end of this manual page, under
+``Module Interface''.
+.PP
+This manual page describes the
+interface as presented to an engine
+once it has been loaded by
+.IR spree .
+A loaded instance of an engine is responsible for a particular
+.IR clique ,
+in which one or more
+.I members
+participate. Messages sent by members
+are interpreted by the engine, which
+responds by making changes to the hierarchical
+.I object
+database held by the clique.
+Behind the scenes
+.I spree
+distributes updates to this database to members
+of the clique as appropriate (see
+.IR spree (4)
+for details).
+.SS "Objects and visibility"
+Objects hold a clique's visible state. An object
+has a unique integer
+.IR id ,
+which is an index into the array
+.IB clique .objects\fR;\fP
+it also holds a set of attribute-value pairs, a type, and
+zero or more child objects. Together, all the objects
+in the clique form a hierarchical tree, rooted at
+the
+.IR "root object"
+(id 0), which always exists.
+Each attribute and each object also has an associated
+.IR "visibility set" ,
+the set of member that sees updates to the attributes or the children
+of the object.  Each member has a unique id;
+in a visibility set (see
+.IR sets (2)),
+a member is ``visible'' if the set contains the member's id.
+.PP
+Note that the visibility set of an object does not alter the visibility
+of that object's attributes, but only that of its children (and of
+their children: in general an object is visible to a member if the
+intersection of all its ancestors' visibility sets contains that
+member).
+.PP
+Objects can be transferred inside the hierarchy from one parent to
+another. If an object is moved to a parent whose visibility conceals it
+from a member, then it will appear to that member to have been deleted;
+if it is later made visible, then it will be recreated for that
+member.
+A clique engine can almost always ignore this technicality,
+except for one thing: the identifier used by a particular member to
+identify an object is not necessarily the same as that used by the clique
+engine. Thus when an engine receives an object id in a member's
+message, it should convert it using the
+.IB member .obj()
+function.
+.SS \fBClique\fP
+The
+.B Clique
+type holds all the objects in a clique. It allows the
+creation of new objects, and provides a way of communicating
+with members directly.
+All data members of a
+.B Clique
+should be treated as read-only.
+.TP 10
+.IB clique .objects
+This array holds the objects in the clique. An object with
+identifier
+.I id
+is found at
+.IB clique .objects[ id ]\fR.\fP
+.TP
+.IB clique .new(\fIarchive\fP, \fIowner\fP)
+.B New
+creates a new clique.
+.I Archive
+is an archive of the game to be created;
+.IB archive \.argv
+should be non-nil; its first element should name
+the engine to be loaded (as a path relative to the
+engine module directory, and without the
+.B .dis
+extension).
+.TP
+.IB clique .newobject(\fIparent\fP,\ \fIvisibility\fP,\ \fIobjtype\fP)
+.B Newobject
+creates a new object at the end
+of
+.IR parent 's
+children;
+If
+.I parent
+is nil, the new object is created under the root object.
+The new object has visibility
+.IR visibility ,
+and type
+.IR objtype .
+An object's type cannot be changed once
+it has been created.
+.TP
+.IB clique .action(\fIcmd\fP,\ \fIobjs\fP,\ \fIrest\fP,\ \fIwhoto\fP)
+.B Action
+sends a message to some members without affecting
+the object hierarchy. It can be used to send transient
+events that have no meaning when stored statically
+(for example, network latency probes).
+The message is sent to the set of members given by
+.IR whoto .
+.I Objs
+is assumed to be a list of object ids, which are
+converted appropriately for each member
+receiving the message; the final
+message is a string built by concatenating
+.IR cmd ,
+the list of object ids, and
+.IR rest ,
+separated by spaces.
+.TP
+.IB clique .breakmsg(\fIwhoto\fP)
+Messages are usually sent to clients in an uninterrupted
+stream (as documented in
+.IR spree (4)),
+with a single read returning a potentially large
+set of messages.
+.B Breakmsg
+arranges that subsequent messages received by the members specified in
+.I whoto
+will see not be merged with messages sent prior to the call to
+.BR breakmsg .
+This is used to enable a new client module to be started
+without needing to pass it data received in the previous read.
+.TP
+.IB clique .member(\fIid\fP)
+.B Member
+yields the member corresponding to identifier
+.IR id ,
+or
+.B nil
+if there is none.
+.TP
+.IB clique .membernamed(\fIname\fP)
+.B Membernamed
+searches for a member of
+.I clique
+named
+.I name
+and returns it if it finds it, otherwise
+.BR nil .
+.TP
+.IB clique .members()
+.B Members
+returns a list of all the members of
+.IR clique ,
+including those that have been suspended.
+.TP 
+.IB clique .owner()
+.B Owner
+returns the name of the owner of the clique;
+i.e. the user that created it.
+.TP
+.IB clique .hangup()
+.B Hangup
+terminates a game and informs all the
+players of that fact.
+.TP
+.IB clique .notify(\fIcliqueid\fP, \fImsg\fP)
+.B Notify
+sends an informational message to another clique.
+The clique so referenced must be either the parent
+or a child of
+.IR clique .
+The message is not sent synchronously,
+and care should be taken not to send messages that
+can cause an indefinite recursion.
+.SS Member
+The
+.B Member
+type represents a member of a clique.
+.TP 10
+.IB member .id
+The member's identifier is an integer  unique across all current members
+of the clique,
+but ids of members that have left the clique will
+be reused.
+There may not be two members of the same name in the
+same clique.
+.TP
+.IB member .name
+.B Name
+holds the authenticated name of the member.
+This is necessarily unique over the members
+of a clique.
+.TP
+.IB member .obj(\fIid\fP)
+.B Obj
+converts from a member's external object
+identifier to the clique's local
+.B Object
+that it represents. It returns
+.B nil
+if there is no such object.
+.TP
+.IB member .del(\fIsuspend\fP)
+.B Del
+deletes
+.I member
+from the clique;
+no more requests from
+.I member
+will be received by the clique engine.
+If
+.I suspend
+is non-zero, if a member of the same name joins again
+it will be allocated the same object id, allowing a member
+to leave and join again without losing state.
+.SS \fBObject\fP
+The
+.B Object
+type is the basic unit of clique engine state.
+An object's children can be selectively concealed
+from members; it holds a set of
+.RI ( attribute ,\  value )
+pairs, each of which can be concealed likewise.
+Where an argument
+.IR r ,
+of
+.B Range
+type is used, it refers to a range of an object's
+children starting at index
+.IB r .start\fR,\fP
+and finishing at
+.IB r .end-1\fR.\fP
+All the data members of an
+.B Object
+should be treated as read-only.
+.TP 10
+.IB obj .setattr(\fIname\fP,\ \fIval\fP,\ \fIvis\fP)
+.B Setattr
+sets attribute
+.I name
+in
+.I obj
+to
+.IR val.
+If the attribute is being created for the
+first time, then it will be given visibility
+.IR vis .
+.I Name
+should be non-empty, and should not
+contain any space characters.
+Note that it is not possible for an attribute
+to refer directly to an object by its identifier;
+if this facility is needed, another identifying
+scheme should be used. This also applies
+to member identifiers, which will change
+if the clique is saved and loaded again.
+.TP
+.IB obj .getattr(\fIname\fP)
+.B Getattr
+yields the current value of the
+attribute
+.I name
+in
+.IR obj .
+If an attribute is not set, it yields
+.BR nil .
+.TP
+.IB obj .delete()
+.B Delete
+removes
+.I obj
+from the object
+hierarchy.
+.TP
+.IB obj .deletechildren(\fIr\fP)
+.B Deletechildren
+deletes children in range
+.I r
+from
+.IR obj .
+.TP
+.IB obj .transfer(\fIr\fP,\ \fIdst\fP,\ \fIi\fP)
+.B Transfer
+transfers the children in range
+.I r
+from
+.I obj
+to just before the object at index
+.I i
+in
+.IR dst .
+It is permissible for
+.I obj
+and
+.I dst
+to be the same object.
+.TP
+.IB obj .setvisibility(\fIvisibility\fP)
+.B Setvisibility
+allows the set of members
+given in
+.I visibility
+to see the children of
+.IR obj ,
+and denies access to all others.
+Members are notified of the change.
+.TP
+.IB obj .setattrvisibility(\fIname\fP,\ \fIvisibility\fP)
+.B Setattrvisibility
+allows the set of members
+given in
+.I visibility
+to see the value of
+.IR obj 's
+attribute
+.IR name ,
+and denies access to all others.
+Members are not notified of the change;
+if there is a need to communicate
+the fact of an attribute becoming invisible to
+members, it should be done by using another
+(visible) attribute to communicate the change.
+.SS "Archives"
+The
+.B Archives
+module provides a means of committing a clique
+to permanent storage and retrieving it later.
+It should first be initialised by calling
+.BR init ,
+passing the
+.B Spree
+module in
+.IR mod .
+.B Write
+writes
+.I clique
+to the file
+.IR file .
+.I Info
+gives a set of attributes and values associated with the clique;
+.I members
+gives the set of clique members for which visibility information
+will be archived; visibility information for other members is forgotten.
+.PP
+.B Read
+opens
+.I file
+and returns it as an
+.B Archive
+adt, say
+.IR a .
+.IB A .argv
+holds the command line arguments to the clique module
+(including the name of the module, its first element);
+.IB a .members
+gives the names of all archived members - the id
+of an archived member is given by its index in the array;
+.IB a .info
+gives the list of attributes an values as stored by
+.BR write ;
+.IB a .objects
+holds the clique objects.
+.B Readheader
+is just like
+.B read
+except that it parses the header only, so will return an
+.B Archive
+adt such that
+.IB a .objects
+is nil.
+.SS "Module Interface"
+An engine module,
+.IR mod ,
+must implement the
+following functions. Where a function returns a string,
+it is interpreted as an error response to the member
+responsible for the request; an empty string signifies
+no error.
+.TP
+.IB mod ->init(\fIsrvmod\fP, \fIclique\fP, \fIargv\fP)
+.B Init
+initialises the clique engine.
+.I Clique
+is the clique that the engine is controlling,
+and
+.I srvmod
+is the
+.B Spree
+module holding its associated data.
+An error response from this function
+causes the clique to be aborted.
+.I Argv
+gives a list of arguments to the engine, starting
+with its module name.
+.TP
+.IB mod ->join(\fImember\fP, \fIe\fP, \fIsuspended\fP)
+.I Member
+has made a request to join the clique;
+an error response causes the request to be
+refused, otherwise the member joins the
+clique.
+.I E
+is a message from the client about how it would like to
+join the clique (e.g.
+.BR join ,
+.BR watch ,
+etc).
+.I Suspended
+is non-zero if the member was previously suspended from the clique.
+.TP
+.IB mod ->leave(\fImember\fP)
+.I Member
+has left the clique.
+If
+.B leave
+returns zero, the member will not be deleted from the
+clique, but merely suspended until they should join again.
+.TP
+.IB mod ->command(\fImember\fP,\ \fIe\fP)
+.I Member
+has sent the command
+.IR e .
+The command usually follows
+the simple message conventions
+used in
+.IR spree (4),
+i.e. simple space-separated tokens.
+.TP
+.IB mod ->notify(\fIcliqueid\fP, \fIs\fP)
+A notification,
+.IR s ,
+has been posted to
+the current clique
+by the clique identified by
+.IR cliqueid .
+The posting clique is either a parent or a child of the current clique.
+.TP
+.IB mod .
+.SH EXAMPLE
+The following is a small, but working example
+of a clique engine that acts as a chat server
+(parsing error checking omitted, and white-space
+compressed to save paper):
+.PP
+.EX
+.ps -1
+.vs -1
+implement Cliquemodule;
+include "sys.m";
+    sys: Sys;
+include "draw.m";
+include "../spree.m";
+    spree: Spree;
+    Clique, Member: import spree;
+clique: ref Clique;
+clienttype(): string
+{
+    return "chat";
+}
+init(g: ref Clique, srvmod: Spree): string
+{
+    (sys, clique, spree) = (load Sys Sys->PATH, g, srvmod);
+    return nil;
+}
+join(nil: ref Member): string
+{
+    return nil;
+}
+leave(nil: ref Member)
+{
+}
+command(member: ref Member, cmd: string): string
+{
+    clique.action("say " + string member.id + " " + cmd, nil, nil, ~0);
+    return nil;
+}
+.ps +1
+.vs +1
+.EE
+.SH SOURCE
+.B /appl/cmd/cliques/spree.b
+.SH "SEE ALSO"
+.IR spree (4),
+.IR spree-objstore (2),
+.IR spree-cardlib (2),
+.IR spree-allow (2),
+.SH BUGS
+The reuse of object ids can lead to
+problems when objects are deleted and
+recreated on the server before clients become
+aware of the changes.